# WeeChat プラグイン API リファレンス

Sébastien Helleu
flashcode@flashtux.org
バージョン 4.8.1

このマニュアルは WeeChat チャットクライアントについての文書で、WeeChat の一部です。

Latest version of this document can be found on this page ↗.

## 1. はじめに

WeeChat (Wee Enhanced Environment for Chat) は無料のチャットクライアントで、高速、軽量、多くのオペレーティングシステムで動くように設計されています。

このマニュアルは WeeChat プラグイン API についての文書で、C 言語プラグインはこの API を使って WeeChat の中核部と通信しています。

## 2. WeeChat プラグイン

プラグインは C 言語のプログラムであり、インターフェースが定義する WeeChat 関数を呼び出すことができます。

この C 言語プログラムはコンパイルの際に WeeChat のソースを必要としません、WeeChat は `/plugin` コマンドでこのプログラムを動的に読み込むことができます。

プラグインを動的にオペレーティングシステムに読み込ませるために、プラグインは必ずダイナミックライブラリにしてください。ファイルの拡張子は GNU/Linux では ".so"、Windows では ".dll" です。

プラグインでは必ず "weechat-plugin.h" ファイルをインクルードしてください (WeeChat ソースコードに含まれています)。このファイルでは WeeChat と通信する際に使う構造体や型が定義されています。

WeeChat 関数を プラグイン API に表示された書式で呼び出すには、以下のグローバルポインタを定義して weechat_plugin_init 関数の中でそれを初期化しなければいけません:

    struct t_weechat_plugin *weechat_plugin;

### 2.1. マクロ

プラグインでは必ず以下のマクロを使ってください (いくつかの変数を定義するために必要です):

WEECHAT_PLUGIN_NAME("name")

  プラグイン名

WEECHAT_PLUGIN_DESCRIPTION("description")

  プラグインの短い説明

WEECHAT_PLUGIN_AUTHOR("author")

  the author name

WEECHAT_PLUGIN_VERSION("1.0")

  プラグインのバージョン番号

WEECHAT_PLUGIN_LICENSE("GPL3")

  プラグインのライセンス

WEECHAT_PLUGIN_PRIORITY(1000)

  プラグインの優先度 (任意、下記参照)

### 2.2. 重要な関数

プラグインでは必ず以下の 2 つの関数を使ってください:

- weechat_plugin_init

- weechat_plugin_end

#### weechat_plugin_init

WeeChat はプラグインを読み込む際にこの関数を呼び出します。

プロトタイプ:

    int weechat_plugin_init (struct t_weechat_plugin *plugin,
                             int argc, char *argv[]);

引数:

- plugin: WeeChat プラグイン構造体へのポインタ。これはグローバルポインタ `weechat_plugin` を初期化する際に使われます

- argc: プラグインに対する引数の数

- argv: プラグインに対する引数 (see below)

戻り値:

- WEECHAT_RC_OK 成功した場合 (プラグインをロードします)

- WEECHAT_RC_ERROR エラーが起きた場合 (プラグインをロードしません)

##### Plugin arguments

When the plugin is loaded by WeeChat, it receives the list of arguments in parameter `argv` and the number of arguments in `argc`.

The arguments can be:

- command line arguments when running the WeeChat binary,

- arguments given to the command `/plugin load xxx`, when the plugin is manually loaded by the user.

When the arguments come from the command line, only these arguments are sent to the plugin:

-a, --no-connect

  WeeChat の起動時にサーバへの自動接続を行わない

-s, --no-script

  スクリプトの自動ロードを止める

plugin:option

  Option for a plugin: only the plugin-related options are sent, for example only the options starting with `irc:` are sent to the plugin called "irc".

##### プラグインの優先度

複数のプラグインが自動ロードされた場合 (たとえば起動時)、WeeChat はまず全てのプラグインをロードし、各プラグインで定義された優先度に従って init 関数を呼び出します。優先度を大きな値にすれば init 関数を呼び出す順番が早くなります

デフォルトの優先度は 1000 です (この値を設定した場合、全てのデフォルトプラグインの後にプラグインをロードします)。

WeeChat のデフォルトプラグインは以下の順番で初期化されます:

Rank | Plugin | Priority
--- | --- | ---
1 | charset | 16000
2 | logger | 15000
3 | exec | 14000
4 | trigger | 13000
5 | spell | 12000
6 | alias | 11000
7 | buflist | 10000
8 | fifo | 9000
9 | typing | 8000
10 | xfer | 7000
11 | irc | 6000
12 | relay | 5000
13 | guile | 4070
14 | lua | 4050
15 | perl | 4040
16 | php | 4030
17 | python | 4020
18 | ruby | 4010
19 | tcl | 4000
20 | script | 3000
21 | fset | 2000

#### weechat_plugin_end

WeeChat プラグインをリロードする際にこの関数を呼び出します。

プロトタイプ:

    int weechat_plugin_end (struct t_weechat_plugin *plugin);

引数:

- plugin: WeeChat プラグイン構造体へのポインタ

戻り値:

- WEECHAT_RC_OK 成功した場合

- WEECHAT_RC_ERROR エラーが起きた場合

### 2.3. プラグインのコンパイル

コンパイルするために WeeChat のソースは不要で、weechat-plugin.h ファイルだけが必要です。

1 つのファイル "toto.c" からなるプラグインは以下のようにコンパイルします (GNU/Linux の場合):

    gcc -fPIC -Wall -c toto.c
    gcc -shared -fPIC -o toto.so toto.o

### 2.4. プラグインを読み込む

toto.so ファイルをシステムのプラグインディレクトリ (例えば /usr/local/lib/weechat/plugins) またはユーザのプラグインディレクトリ (例えば /home/user/.local/share/weechat/plugins) にコピーしてください。

WeeChat の中で:

    /plugin load toto

### 2.5. プラグインの例

コマンド `/double` を追加するプラグインの例: 引数を 2 倍して現在のバッファに表示するか、コマンドを 2 回実行する (これは実用的なコマンドというよりも、ただの例です!):

    #include <stdlib.h>

    #include "weechat-plugin.h"

    WEECHAT_PLUGIN_NAME("double");
    WEECHAT_PLUGIN_DESCRIPTION("Test plugin for WeeChat");
    WEECHAT_PLUGIN_AUTHOR("Sébastien Helleu <flashcode@flashtux.org>");
    WEECHAT_PLUGIN_VERSION("0.1");
    WEECHAT_PLUGIN_LICENSE("GPL3");

    struct t_weechat_plugin *weechat_plugin = NULL;

    /* "/double" コマンドのコールバック*/

    int
    command_double_cb (const void *pointer, void *data,
                       struct t_gui_buffer *buffer,
                       int argc, char **argv, char **argv_eol)
    {
        /* C 言語コンパイラ向けに必要 */
        (void) pointer;
        (void) data;
        (void) buffer;
        (void) argv;

        if (argc > 1)
        {
            weechat_command (NULL, argv_eol[1]);
            weechat_command (NULL, argv_eol[1]);
        }

        return WEECHAT_RC_OK;
    }

    int
    weechat_plugin_init (struct t_weechat_plugin *plugin,
                         int argc, char *argv[])
    {
        weechat_plugin = plugin;

        weechat_hook_command ("double",
                              "Display two times a message "
                              "or execute two times a command",
                              "message | command",
                              "message: message to display two times\n"
                              "command: command to execute two times",
                              NULL,
                              &command_double_cb, NULL, NULL);

        return WEECHAT_RC_OK;
    }

    int
    weechat_plugin_end (struct t_weechat_plugin *plugin)
    {
        /* C 言語コンパイラ向けに必要 */
        (void) plugin;

        return WEECHAT_RC_OK;
    }

## 3. プラグイン API

以下の章では API 関数をカテゴリごとに説明しています。

それぞれの関数について、以下の内容が記載されています:

- 関数の説明、

- C 言語のプロトタイプ、

- 引数の詳細、

- 戻り値、

- C 言語での使用例、

- Python スクリプトでの使用例 (他のスクリプト言語を使う場合も文法は似ています)。

### 3.1. Registering

Functions to register a script: used only by scripting API, not the C API.

#### register

Register the script.

For more information, see the WeeChat scripting guide ↗.

スクリプト (Python) での使用例:

    # プロトタイプ
    def register(name: str, author: str, version: str, license: str, description: str, shutdown_function: str, charset: str) -> int: ...

注記 | This function is not available in the C API.

### 3.2. プラグイン

プラグインに関する情報を取得する関数。

#### plugin_get_name

プラグインの名前を取得。

プロトタイプ:

    const char *weechat_plugin_get_name (struct t_weechat_plugin *plugin);

引数:

- plugin: WeeChat プラグイン構造体へのポインタ (NULL でも可)

戻り値:

- プラグインの名前、WeeChat コアの場合は "core" (プラグインへのポインタが NULL の場合)

C 言語での使用例:

    const char *name = weechat_plugin_get_name (plugin);

スクリプト (Python) での使用例:

    # プロトタイプ
    def plugin_get_name(plugin: str) -> str: ...

    # 例
    plugin = weechat.buffer_get_pointer(weechat.current_buffer(), "plugin")
    name = weechat.plugin_get_name(plugin)

### 3.3. 文字列

以下の多くの文字列関数は標準的な C 言語の関数でも定義されていますが、この API 関数を使うことを推奨します。なぜなら、これらの関数は文字列を UTF-8 とロケールに準じて取り扱うようになっているからです。

#### charset_set

新しいプラグインの文字セットを設定する (デフォルトの文字セットは UTF-8 です、このためプラグインで UTF-8 を使う場合は、この関数を呼び出す必要はありません。

プロトタイプ:

    void weechat_charset_set (const char *charset);

引数:

- charset: 新たに利用する文字セット

C 言語での使用例:

    weechat_charset_set ("iso-8859-1");

スクリプト (Python) での使用例:

    # プロトタイプ
    def charset_set(charset: str) -> int: ...

    # 例
    weechat.charset_set("iso-8859-1")

#### iconv_to_internal

文字列の文字セットを WeeChat の内部文字セット (UTF-8) に変換。

プロトタイプ:

    char *weechat_iconv_to_internal (const char *charset, const char *string);

引数:

- charset: 変換元の文字列の文字セット

- string: 変換元の文字列

戻り値:

- 文字セットを変換した文字列 (使用後には必ず "free" を呼び出して領域を開放してください)

C 言語での使用例:

    char *str = weechat_iconv_to_internal ("iso-8859-1", "iso string: é à");
    /* ... */
    free (str);

スクリプト (Python) での使用例:

    # プロトタイプ
    def iconv_to_internal(charset: str, string: str) -> str: ...

    # 例
    str = weechat.iconv_to_internal("iso-8859-1", "iso string: é à")

#### iconv_from_internal

文字列の文字セットを WeeChat の内部文字セット (UTF-8) から別の文字セットに変換。

プロトタイプ:

    char *weechat_iconv_from_internal (const char *charset, const char *string);

引数:

- charset: 変換先の文字列の文字セット

- string: 変換元の文字列

戻り値:

- 文字セットを変換した文字列 (使用後には必ず "free" を呼び出して領域を開放してください)

C 言語での使用例:

    char *str = weechat_iconv_from_internal ("iso-8859-1", "utf-8 string: é à");
    /* ... */
    free (str);

スクリプト (Python) での使用例:

    # プロトタイプ
    def iconv_from_internal(charset: str, string: str) -> str: ...

    # 例
    str = weechat.iconv_from_internal("iso-8859-1", "utf-8 string: é à")

#### gettext

翻訳済み文字列を返す (設定言語に依存)。

プロトタイプ:

    const char *weechat_gettext (const char *string);

引数:

- string: 翻訳元の文字列

戻り値:

- 翻訳済み文字列または string (未翻訳の場合)

C 言語での使用例:

    char *str = weechat_gettext ("hello");

スクリプト (Python) での使用例:

    # プロトタイプ
    def gettext(string: str) -> str: ...

    # 例
    str = weechat.gettext("hello")

#### ngettext

count 引数を元に単数形または複数形で、翻訳済み文字列を返す。

プロトタイプ:

    const char *weechat_ngettext (const char *string, const char *plural,
                                  int count);

引数:

- string: 翻訳元の文字列、単数形

- plural: 翻訳元の文字列、複数形

- count: 単数形と複数形のどちらを返すかの判断に使います (選択は設定言語に依存)

戻り値:

- 翻訳済み文字列または string / plural (未翻訳の場合)

C 言語での使用例:

    char *str = weechat_ngettext ("file", "files", num_files);

スクリプト (Python) での使用例:

    # プロトタイプ
    def ngettext(string: str, plural: str, count: int) -> str: ...

    # 例
    num_files = 2
    str = weechat.ngettext("file", "files", num_files)

#### asprintf

WeeChat ≥ 4.3.0.

Format a message in a string allocated by the function.

注記 | This function is defined for systems where the GNU function `asprintf()` is not available. The behavior is almost the same except that `*result` is set to NULL on error.

プロトタイプ:

    int weechat_asprintf (char **result, const char *fmt, ...);

引数:

- result: pointer to a string pointer

- fmt: format string

戻り値:

- number of bytes written in `*result` (excluding the final null byte), a negative value in case of error.

C 言語での使用例:

    char *str;

    if (weechat_asprintf (&str, "%s, %d", "test", 42) >= 0)
    {
        /* *str == "test, 42" */
        /* ... */
        free (str);
    }
    else
    {
        /* error: *str == NULL */
    }

注記 | スクリプト API ではこの関数を利用できません。

#### strndup

Return duplicated string, with a max number of bytes.

プロトタイプ:

    char *weechat_strndup (const char *string, int bytes);

引数:

- string: 複製元の文字列

- bytes: max bytes to duplicate

戻り値:

- 複製した文字列 (使用後には必ず "free" を呼び出して領域を開放してください)

C 言語での使用例:

    char *str = weechat_strndup ("abcdef", 3);  /* result: "abc" */
    /* ... */
    free (str);

注記 | スクリプト API ではこの関数を利用できません。

#### string_cut

WeeChat バージョン 3.3 以上で利用可。

Cut a string after a given number of chars, add an optional suffix after the string if it is cut.

プロトタイプ:

    char *weechat_string_cut (const char *string, int length, int count_suffix, int screen, const char *cut_suffix);

引数:

- string: string to cut

- length: max chars

- count_suffix: if 1, the length of suffix is counted in the max length

- screen: if 1, the cut is based on width of chars displayed

- cut_suffix: the suffix added after the string if it is cut

戻り値:

- cut string (must be freed by calling "free" after use)

C 言語での使用例:

    char *str = weechat_string_cut ("this is a test", 5, 1, 1, "…");  /* result: "this…" */
    /* ... */
    free (str);

注記 | スクリプト API ではこの関数を利用できません。

#### string_tolower

WeeChat バージョン 3.8 で更新。

Return a string with uppercase letters converted to lowercase.

注記 | Behavior has changed in version 3.8: now all uppercase letters are properly converted to lowercase (by calling function `towlower`), in addition to the range `A` to `Z`. Moreover, a newly allocated string is returned and must be freed after use.

プロトタイプ:

    char *weechat_string_tolower (const char *string);

引数:

- string: 変換元の文字列

戻り値:

- string with lowercase letters (must be freed by calling "free" after use)

C 言語での使用例:

    char *str = weechat_string_tolower ("ABCD_É");  /* result: "abcd_é" */
    /* ... */
    free (str);

注記 | スクリプト API ではこの関数を利用できません。

#### string_toupper

WeeChat バージョン 3.8 で更新。

Return a string with lowercase letters converted to uppercase.

注記 | Behavior has changed in version 3.8: now all lowercase letters are properly converted to uppercase (by calling function `towupper`), in addition to the range `a` to `z`. Moreover, a newly allocated string is returned and must be freed after use.

プロトタイプ:

    char *weechat_string_toupper (const char *string);

引数:

- string: 変換元の文字列

戻り値:

- string with uppercase letters (must be freed by calling "free" after use)

C 言語での使用例:

    char *str = weechat_string_toupper ("abcd_é");  /* result: "ABCD_É" */
    /* ... */
    free (str);

注記 | スクリプト API ではこの関数を利用できません。

#### string_charcmp

WeeChat バージョン 1.0, 3.8 で更新。

2 つの 文字を比較。

プロトタイプ:

    int weechat_string_charcmp (const char *string1, const char *string2);

引数:

- string1: 1 番目の比較文字列

- string2: 2 番目の比較文字列

Return value:

- arithmetic result of subtracting the first UTF-8 char in string2 from the first UTF-8 char in string1:

  - < 0 if char1 < char2

  - 0 if char1 == char2

  - > 0 if char1 > char2

C 言語での使用例:

    int diff = weechat_string_charcmp ("aaa", "ccc");  /* == -2 */

注記 | スクリプト API ではこの関数を利用できません。

#### string_charcasecmp

WeeChat バージョン 1.0, 3.8 で更新。

大文字小文字の違いを無視して、2 つの 文字を比較。

注記 | Behavior has changed in version 3.8: now all uppercase letters are properly converted to lowercase (by calling function `towlower`), in addition to the range `A` to `Z`.

プロトタイプ:

    int weechat_string_charcasecmp (const char *string1, const char *string2);

引数:

- string1: 1 番目の比較文字列

- string2: 2 番目の比較文字列

Return value:

- arithmetic result of subtracting the first UTF-8 char in string2 (converted to lowercase) from the first UTF-8 char in string1 (converted to lowercase):

  - < 0 if char1 < char2

  - 0 if char1 == char2

  - > 0 if char1 > char2

C 言語での使用例:

    int diff = weechat_string_charcasecmp ("aaa", "CCC");  /* == -2 */

注記 | スクリプト API ではこの関数を利用できません。

#### strcmp

WeeChat ≥ 3.8

Case-sensitive string comparison.

プロトタイプ:

    int weechat_strcmp (const char *string1, const char *string2);

引数:

- string1: 1 番目の比較対象の文字列

- string2: 2 番目の比較対象の文字列

Return value:

- arithmetic result of subtracting the last compared UTF-8 char in string2 from the last compared UTF-8 char in string1:

  - < 0 if string1 < string2

  - 0 if string1 == string2

  - > 0 if string1 > string2

C 言語での使用例:

    int diff = weechat_strcmp ("aaa", "ccc");  /* == -2 */

注記 | スクリプト API ではこの関数を利用できません。

#### strncmp

WeeChat ≥ 3.8

Case-sensitive string comparison, for max chars.

プロトタイプ:

    int weechat_strncmp (const char *string1, const char *string2, int max);

引数:

- string1: 1 番目の比較対象の文字列

- string2: 2 番目の比較対象の文字列

- max: 比較する文字数の最大値

Return value:

- arithmetic result of subtracting the last compared UTF-8 char in string2 from the last compared UTF-8 char in string1:

  - < 0 if string1 < string2

  - 0 if string1 == string2

  - > 0 if string1 > string2

C 言語での使用例:

    int diff = weechat_strncmp ("aabb", "aacc", 2);  /* == 0 */

注記 | スクリプト API ではこの関数を利用できません。

#### strcasecmp

WeeChat バージョン 1.0, 3.8 で更新。

Case-insensitive string comparison.

注記 | Behavior has changed in version 3.8: now all uppercase letters are properly converted to lowercase (by calling function `towlower`), in addition to the range `A` to `Z`.

プロトタイプ:

    int weechat_strcasecmp (const char *string1, const char *string2);

引数:

- string1: 1 番目の比較対象の文字列

- string2: 2 番目の比較対象の文字列

Return value:

- arithmetic result of subtracting the last compared UTF-8 char in string2 (converted to lowercase) from the last compared UTF-8 char in string1 (converted to lowercase):

  - < 0 if string1 < string2

  - 0 if string1 == string2

  - > 0 if string1 > string2

C 言語での使用例:

    int diff;
    diff = weechat_strcasecmp ("aaa", "CCC");    /* == -2 */
    diff = weechat_strcasecmp ("noël", "NOËL");  /* == 0  */

注記 | スクリプト API ではこの関数を利用できません。

#### strcasecmp_range

WeeChat バージョン 0.3.7 以上で利用可、バージョン 1.0, 3.8 で更新。

大文字小文字を無視する文字範囲の幅を使い、ロケールと大文字小文字を無視して文字列を比較。

プロトタイプ:

    int weechat_strcasecmp_range (const char *string1, const char *string2, int range);

引数:

- string1: 1 番目の比較対象の文字列

- string2: 2 番目の比較対象の文字列

- range: 大文字小文字を無視する文字範囲の幅、例:

  - 26: `A-Z` を `a-z` のように変換して比較

  - 29: `A-Z [ \ ]` を `a-z { | }` のように変換して比較

  - 30: `A-Z [ \ ] ^` を `a-z { | } ~` のように変換して比較

注記 | 29 と 30 は IRC など一部のプロトコルで使います。

Return value:

- arithmetic result of subtracting the last compared UTF-8 char in string2 (converted to lowercase) from the last compared UTF-8 char in string1 (converted to lowercase):

  - < 0 if string1 < string2

  - 0 if string1 == string2

  - > 0 if string1 > string2

C 言語での使用例:

    int diff = weechat_strcasecmp_range ("nick{away}", "NICK[away]", 29);  /* == 0 */

注記 | スクリプト API ではこの関数を利用できません。

#### strncasecmp

WeeChat バージョン 1.0, 3.8 で更新。

Case-insensitive string comparison, for max chars.

注記 | Behavior has changed in version 3.8: now all uppercase letters are properly converted to lowercase (by calling function `towlower`), in addition to the range `A` to `Z`.

プロトタイプ:

    int weechat_strncasecmp (const char *string1, const char *string2, int max);

引数:

- string1: 1 番目の比較対象の文字列

- string2: 2 番目の比較対象の文字列

- max: 比較する文字数の最大値

Return value:

- arithmetic result of subtracting the last compared UTF-8 char in string2 (converted to lowercase) from the last compared UTF-8 char in string1 (converted to lowercase):

  - < 0 if string1 < string2

  - 0 if string1 == string2

  - > 0 if string1 > string2

C 言語での使用例:

    int diff = weechat_strncasecmp ("aabb", "AACC", 2);  /* == 0 */

注記 | スクリプト API ではこの関数を利用できません。

#### strncasecmp_range

WeeChat バージョン 0.3.7 以上で利用可、バージョン 1.0, 3.8 で更新。

大文字小文字を無視する文字範囲の幅を使い、ロケールと大文字小文字を無視して max 文字だけ文字列を比較。

プロトタイプ:

    int weechat_strncasecmp_range (const char *string1, const char *string2, int max, int range);

引数:

- string1: 1 番目の比較対象の文字列

- string2: 2 番目の比較対象の文字列

- max: 比較する文字数の最大値

- range: 大文字小文字を無視する文字範囲の幅、例:

  - 26: `A-Z` を `a-z` のように変換して比較

  - 29: `A-Z [ \ ]` を `a-z { | }` のように変換して比較

  - 30: `A-Z [ \ ] ^` を `a-z { | } ~` のように変換して比較

注記 | 29 と 30 は IRC など一部のプロトコルで使います。

Return value:

- arithmetic result of subtracting the last compared UTF-8 char in string2 (converted to lowercase) from the last compared UTF-8 char in string1 (converted to lowercase):

  - < 0 if string1 < string2

  - 0 if string1 == string2

  - > 0 if string1 > string2

C 言語での使用例:

    int diff = weechat_strncasecmp_range ("nick{away}", "NICK[away]", 6, 29);  /* == 0 */

注記 | スクリプト API ではこの関数を利用できません。

#### strcmp_ignore_chars

WeeChat バージョン 1.0, 3.8 で更新。

String comparison ignoring some chars.

プロトタイプ:

    int weechat_strcmp_ignore_chars (const char *string1, const char *string2,
                                     const char *chars_ignored,
                                     int case_sensitive);

引数:

- string1: 1 番目の比較対象の文字列

- string2: 2 番目の比較対象の文字列

- chars_ignored: 無視する文字

- case_sensitive: 大文字小文字を区別して比較する場合は 1、区別しない場合は 0

注記 | Behavior has changed in version 3.8 when case_sensitive is set to 0: now all uppercase letters are properly converted to lowercase (by calling function `towlower`), in addition to the range `A` to `Z`.

Return value:

- arithmetic result of subtracting the last compared UTF-8 char in string2 (converted to lowercase if case_sensitive is set to 0) from the last compared UTF-8 char in string1 (converted to lowercase if case_sensitive is set to 0):

  - < 0 if string1 < string2

  - 0 if string1 == string2

  - > 0 if string1 > string2

C 言語での使用例:

    int diff = weechat_strcmp_ignore_chars ("a-b", "--a-e", "-", 1);  /* == -3 */

注記 | スクリプト API ではこの関数を利用できません。

#### strcasestr

WeeChat バージョン 1.3, 3.8 で更新。

Case-insensitive string search.

注記 | Behavior has changed in version 3.8: now all uppercase letters are properly converted to lowercase (by calling function `towlower`), in addition to the range `A` to `Z`.

プロトタイプ:

    const char *weechat_strcasestr (const char *string, const char *search);

引数:

- string: 文字列

- search: string 内を検索する文字

戻り値:

- 見つかった文字列へのポインタ、見つからない場合は NULL (WeeChat バージョン 1.3 以上の場合: 返されるポインタは const char * であり、char * ではありません)

C 言語での使用例:

    const char *pos = weechat_strcasestr ("aBcDeF", "de");  /* result: pointer to "DeF" */

注記 | スクリプト API ではこの関数を利用できません。

#### strlen_screen

WeeChat ≥ 0.4.2, updated in 3.8.

Return number of chars needed on screen to display UTF-8 string.

WeeChat color codes are skipped and don’t count in the result (this is the only difference with the function utf8_strlen_screen).

プロトタイプ:

    int weechat_strlen_screen (const char *string);

引数:

- string: 文字列

戻り値:

- UTF-8 文字列を画面上に表示するために必要な画面幅

C 言語での使用例:

    int length_on_screen = weechat_strlen_screen ("é");  /* == 1 */

スクリプト (Python) での使用例:

    # プロトタイプ
    def strlen_screen(string: str) -> int: ...

    # 例
    length = weechat.strlen_screen("é")  # 1

#### string_match

WeeChat バージョン 1.0, 3.8 で更新。

文字列がマスクにマッチするか確認。

プロトタイプ:

    int weechat_string_match (const char *string, const char *mask,
                              int case_sensitive);

引数:

- string: 文字列

- mask: ワイルドカード (`*`) を含むマスク、各ワイルドカードは文字列中の 0 個またはそれ以上の文字にマッチします

- case_sensitive: 大文字小文字を区別する場合は 1、区別しない場合は 0

注記 | WeeChat バージョン 1.0 以上の場合、ワイルドカードをマスクの内部で使うことが可能です (マスクの最初および最後だけではありません)。

注記 | Behavior has changed in version 3.8 when case_sensitive is set to 0: now all uppercase letters are properly converted to lowercase (by calling function `towlower`), in addition to the range `A` to `Z`.

戻り値:

- マスクにマッチした場合は 1、それ以外は 0

C 言語での使用例:

    int match1 = weechat_string_match ("abcdef", "abc*", 0);   /* == 1 */
    int match2 = weechat_string_match ("abcdef", "*dd*", 0);   /* == 0 */
    int match3 = weechat_string_match ("abcdef", "*def", 0);   /* == 1 */
    int match4 = weechat_string_match ("abcdef", "*de*", 0);   /* == 1 */
    int match5 = weechat_string_match ("abcdef", "*b*d*", 0);  /* == 1 */

スクリプト (Python) での使用例:

    # プロトタイプ
    def string_match(string: str, mask: str, case_sensitive: int) -> int: ...

    # 例
    match1 = weechat.string_match("abcdef", "abc*", 0)   # == 1
    match2 = weechat.string_match("abcdef", "*dd*", 0)   # == 0
    match3 = weechat.string_match("abcdef", "*def", 0)   # == 1
    match4 = weechat.string_match("abcdef", "*de*", 0)   # == 1
    match5 = weechat.string_match("abcdef", "*b*d*", 0)  # == 1

#### string_match_list

WeeChat ≥ 2.5, updated in 3.8.

文字列が否定マスク (書式: "!word") を含むマスクリストにマッチするか確認します。否定マスクは通常のマスクよりも優先度が高いです。

プロトタイプ:

    int weechat_string_match_list (const char *string, const char **masks,
                                   int case_sensitive);

引数:

- string: 文字列

- masks: マスクリスト、リストの最後には NULL をつけてください; 各マスクは関数 string_match で文字列と比較されます

- case_sensitive: 大文字と小文字を区別する場合は 1、区別しない場合は 0

注記 | Behavior has changed in version 3.8 when case_sensitive is set to 0: now all uppercase letters are properly converted to lowercase (by calling function `towlower`), in addition to the range `A` to `Z`.

戻り値:

- 1 if string matches list of masks (at least one mask matches and no negative mask matches), otherwise 0

- 文字列がマスクリストとマッチした場合 (1 つ以上のマスクにマッチするか、否定マスクに 1 つもマッチしない場合) は 1、それ以外の場合は 0

C 言語での使用例:

    const char *masks[3] = { "*", "!abc*", NULL };
    int match1 = weechat_string_match_list ("abc", masks, 0);     /* == 0 */
    int match2 = weechat_string_match_list ("abcdef", masks, 0);  /* == 0 */
    int match3 = weechat_string_match_list ("def", masks, 0);     /* == 1 */

スクリプト (Python) での使用例:

    # プロトタイプ
    def string_match_list(string: str, masks: str, case_sensitive: int) -> int: ...

    # 例
    match1 = weechat.string_match("abc", "*,!abc*", 0)     # == 0
    match2 = weechat.string_match("abcdef", "*,!abc*", 0)  # == 0
    match3 = weechat.string_match("def", "*,!abc*", 0)     # == 1

#### string_expand_home

WeeChat バージョン 0.3.3 以上で利用可。

文字列が `~` から始まる場合はこれをホームディレクトリで置換。文字列が `~` から始まっていない場合は同じ文字列を返す。

プロトタイプ:

    char *weechat_string_expand_home (const char *path);

引数:

- path: パス

戻り値:

- `~` から始まるパスをホームディレクトリで置換したパス (使用後には必ず "free" を呼び出して領域を開放してください)

C 言語での使用例:

    char *str = weechat_string_expand_home ("~/file.txt");
    /* result: "/home/user/file.txt" */
    /* ... */
    free (str);

注記 | スクリプト API ではこの関数を利用できません。

#### string_eval_path_home

WeeChat ≥ 1.3, updated in 3.2.

3 段階でパスを評価します:

1. replace leading `%h` by a WeeChat directory (data by default),

2. 先頭の `~` をユーザのホームディレクトリで置換し (string_expand_home を実行し)、

3. 変数を評価します (string_eval_expression を参照してください)。

プロトタイプ:

    char *weechat_string_eval_path_home (const char *path,
                                         struct t_hashtable *pointers,
                                         struct t_hashtable *extra_vars,
                                         struct t_hashtable *options);

引数:

- path: パス

- pointers: 関数に渡されるハッシュテーブル string_eval_expression

- extra_vars: 関数に渡されるハッシュテーブル string_eval_expression

- options: hashtable for call to function string_eval_expression, with one extra key supported:

  - directory: WeeChat directory to use when replacing `%h`, one of:

    - config

    - data (default)

    - cache

    - runtime

戻り値:

- 評価済みのパス (使用後には必ず "free" を呼び出して領域を開放してください)

C 言語での使用例:

    char *str = weechat_string_eval_path_home ("${weechat_config_dir}/test.conf", NULL, NULL, NULL);
    /* result: "/home/user/.config/weechat/test.conf" */
    /* ... */
    free (str);

スクリプト (Python) での使用例:

    # プロトタイプ
    def string_eval_path_home(path: str, pointers: Dict[str, str], extra_vars: Dict[str, str], options: Dict[str, str]) -> str: ...

    # 例
    path = weechat.string_eval_path_home("${weechat_config_dir}/test.conf", {}, {}, {})
    # path == "/home/user/.config/weechat/test.conf"

#### string_remove_quotes

文字列の最初と最後から引用符を削除 (最初の引用符の前と最後の引用符の後にある空白文字は無視)。

プロトタイプ:

    char *weechat_string_remove_quotes (const char *string, const char *quotes);

引数:

- string: 文字列

- quotes: 引用符のリストを含む文字列

戻り値:

- 最初と最後から引用符を削除した文字列 (使用後には必ず "free" を呼び出して領域を開放してください)

C 言語での使用例:

    char *str = weechat_string_remove_quotes (string, " 'I can't' ", "'");
    /* result: "I can't" */
    /* ... */
    free (str);

注記 | スクリプト API ではこの関数を利用できません。

#### string_strip

文字列の最初と最後から文字を削除する。

プロトタイプ:

    char *weechat_string_strip (const char *string, int left, int right,
                                const char *chars);

引数:

- string: 文字列

- left: 0 以外の場合は左側の文字を削除

- right: 0 以外の場合は右側の文字を削除

- chars: 削除する文字を含む文字列

戻り値:

- 文字を削除した文字列 (使用後には必ず "free" を呼び出して領域を開放してください)

C 言語での使用例:

    char *str = weechat_string_strip (".abc -", 0, 1, "- .");  /* result: ".abc" */
    /* ... */
    free (str);

注記 | スクリプト API ではこの関数を利用できません。

#### string_convert_escaped_chars

WeeChat バージョン 1.0 以上で利用可。

エスケープ文字を値に変換:

- `\"`: 二重引用符

- `\\`: バックスラッシュ

- `\a`: アラート (BEL)

- `\b`: バックスペース

- `\e`: エスケープ

- `\f`: 改ページ

- `\n`: 改行

- `\r`: キャリッジリターン

- `\t`: 水平タブ

- `\v`: 垂直タブ

- `\0ooo`: 文字の 8 進数表現 (`ooo` は 0 桁から 3 桁)

- `\xhh`: 文字の 16 進数表現 (`hh` は 1 桁から 2 桁)

- `\uhhhh`: ユニコード文字の 16 進数表現 (`hhhh` は 1 桁から 4 桁)

- `\Uhhhhhhhh`: ユニコード文字の 16 進数表現 (`hhhhhhhh` は 1 桁から 8 桁)

プロトタイプ:

    char *weechat_string_convert_escaped_chars (const char *string);

引数:

- string: 文字列

戻り値:

- エスケープ文字を値に変換した文字列 (使用後には必ず "free" を呼び出して領域を開放してください)

C 言語での使用例:

    char *str = weechat_string_convert_escaped_chars ("snowman: \\u2603");
    /* str == "snowman: ☃" */
    /* ... */
    free (str);

注記 | スクリプト API ではこの関数を利用できません。

#### string_mask_to_regex

マスクから正規表現を作りこれを返す、マスク用の特殊文字は `*` のみ。これ以外の文字はすべてエスケープされます。

プロトタイプ:

    char *weechat_string_mask_to_regex (const char *mask);

引数:

- mask: マスク

戻り値:

- 正規表現の文字列 (使用後には必ず "free" を呼び出して領域を開放してください)

C 言語での使用例:

    char *str_regex = weechat_string_mask_to_regex ("test*mask");
    /* result: "test.*mask" */
    /* ... */
    free (str_regex);

スクリプト (Python) での使用例:

    # プロトタイプ
    def string_mask_to_regex(mask: str) -> str: ...

    # 例
    regex = weechat.string_mask_to_regex("test*mask")  # "test.*mask"

#### string_regex_flags

WeeChat バージョン 0.3.7 以上で利用可。

フラグ以降の文字列へのポインタと正規表現をコンパイルするためのフラグ付きマスクを返す

プロトタイプ:

    const char *weechat_string_regex_flags (const char *regex, int default_flags, int *flags)

引数:

- regex: POSIX 拡張正規表現

- default_flags: 以下の値を組み合わせたもの (`man regcomp` を参照):

  - REG_EXTENDED

  - REG_ICASE

  - REG_NEWLINE

  - REG_NOSUB

- flags: ポインタ値は正規表現中で指定されたフラグと一緒にセットされます (デフォルトのフラグ + 正規表現中で指定されたフラグ)

フラグは必ず正規表現の最初につけてください。書式: "(?eins-eins)string"。

利用可能なフラグ:

- e: POSIX 拡張正規表現 (REG_EXTENDED)

- i: 大文字小文字を区別しない (REG_ICASE)

- n: 任意の文字にマッチする演算子を改行文字にマッチさせない (REG_NEWLINE)

- s: マッチした部分文字列の位置を使わない (REG_NOSUB)

戻り値:

- regex からフラグを除いた位置へのポインタ

C 言語での使用例:

    const char *regex = "(?i)test";
    int flags;
    const char *ptr_regex = weechat_string_regex_flags (regex, REG_EXTENDED, &flags);
    /* ptr_regex == "test", flags == REG_EXTENDED | REG_ICASE */

注記 | スクリプト API ではこの関数を利用できません。

#### string_regcomp

WeeChat バージョン 0.3.7 以上で利用可。

文字列の最初に含まれるオプションフラグを使って POSIX 拡張正規表現をコンパイル (フラグの書式については string_regex_flags を参照)。

プロトタイプ:

    int weechat_string_regcomp (void *preg, const char *regex, int default_flags)

引数:

- preg: regex_t 構造体へのポインタ

- regex: POSIX 拡張正規表現

- default_flags: 以下の値の組み合わせ (`man regcomp` を参照):

  - REG_EXTENDED

  - REG_ICASE

  - REG_NEWLINE

  - REG_NOSUB

戻り値:

- `regcomp` 関数と同じ戻り値 (成功の場合は 0、エラーが起きた場合は 0 以外、`man regcomp` を参照)

注記 | Regular expression preg must be cleaned by calling "regfree" after use, if the function returned 0 (OK).

C 言語での使用例:

    regex_t my_regex;
    if (weechat_string_regcomp (&my_regex, "(?i)test", REG_EXTENDED) == 0)
    {
        /* OK */
        /* ... */
        regfree (&my_regex);
    }
    else
    {
        /* error */
        /* ... */
    }

注記 | スクリプト API ではこの関数を利用できません。

#### string_has_highlight

ハイライトしたい単語のリストを元に、1 箇所以上マッチする部分があるか調べる。

プロトタイプ:

    int weechat_string_has_highlight (const char *string,
                                      const char highlight_words);

引数:

- string: 文字列

- highlight_words: ハイライトしたい単語のリスト、コンマ区切り

戻り値:

- ハイライトしたい単語にマッチする部分が 1 箇所以上ある場合は 1、それ以外は 0

C 言語での使用例:

    int hl = weechat_string_has_highlight ("my test string", "test,word2");  /* == 1 */

スクリプト (Python) での使用例:

    # プロトタイプ
    def string_has_highlight(string: str, highlight_words: str) -> int: ...

    # 例
    highlight = weechat.string_has_highlight("my test string", "test,word2")  # 1

#### string_has_highlight_regex

WeeChat バージョン 0.3.4 以上で利用可。

POSIX 拡張正規表現を使って、文字列中から正規表現にマッチする部分が 1 つ以上あるか確認。
文字列を正規表現にマッチさせるには、マッチする部分の前後に区切り文字 (アルファベット、`-`、`_`、`|` 以外) がなければいけません。

プロトタイプ:

    int weechat_string_has_highlight_regex (const char *string, const char *regex);

引数:

- string: 文字列

- regex: POSIX 拡張正規表現

戻り値:

- ハイライトしたい正規表現にマッチする部分が 1 箇所以上ある場合は 1、それ以外は 0

C 言語での使用例:

    int hl = weechat_string_has_highlight_regex ("my test string", "test|word2");  /* == 1 */

スクリプト (Python) での使用例:

    # プロトタイプ
    def string_has_highlight_regex(string: str, regex: str) -> int: ...

    # 例
    highlight = weechat.string_has_highlight_regex("my test string", "test|word2")  # 1

#### string_replace

マッチした全ての文字列を別の文字列で置換。

プロトタイプ:

    char *weechat_string_replace (const char *string, const char *search,
                                  const char *replace);

引数:

- string: 文字列

- search: マッチさせる文字列

- replace: search を置き換える文字列

戻り値:

- search を replace で置き換えた文字列 (使用後には必ず "free" を呼び出して領域を開放してください)

C 言語での使用例:

    char *str = weechat_string_replace ("test", "s", "x");  /* result: "text" */
    /* ... */
    free (str);

注記 | スクリプト API ではこの関数を利用できません。

#### string_replace_regex

WeeChat バージョン 1.0 以上で利用可。

文字列中のテキストを正規表現、置換先テキスト、任意指定のコールバックを使って置換。

プロトタイプ:

    char *weechat_string_replace_regex (const char *string, void *regex,
                                        const char *replace, const char reference_char,
                                        char *(*callback)(void *data, const char *text),
                                        void *callback_data);

引数:

- string: 文字列

- regex: WeeChat 関数 string_regcomp または regcomp (`man regcomp` を参照) でコンパイルした正規表現へのポインタ (regex_t 構造体)

- replace: 置換先テキスト、以下のリファレンスを使うことができます:

  - `$0` から `$99`: 正規表現中の 0 から 99 番目のマッチ部分 (0 はマッチする部分全体、1 から 99 は括弧で括られたグループ)

  - `$+`: 最後にマッチした部分 (最大の番号を持つマッチ部分)

  - `$.*N`: `*` で全ての文字を置換した `N` 番目 (`+` または `0` から `99` を使うことができます) のマッチ部分 (`*` 文字は空白 (32) から `~` (126) までの任意の文字を使うことができます)

- reference_char: マッチ部分を参照するための文字 (通常は `$`)

- callback: replace に含まれる各リファレンスに対して呼び出される任意指定可能なコールバック関数 (マッチ部分を文字で置換する場合を除く); このコールバックは必ず以下の値を返してください:

  - 新しく割り当てられた文字列: 文字列を置換先テキストとして使います (文字列は使用後に開放されます)

  - NULL: コールバックに渡されたテキストを置換先テキストとして使います (文字列に変更を加えません)

- callback_data: callback コールバックを呼び出す際にコールバックに渡すポインタ

戻り値:

- 置換されたテキストを含む文字、問題が起きた場合は NULL (使用後には必ず "free" を呼び出して領域を開放してください)

C 言語での使用例:

    regex_t my_regex;
    char *string;
    if (weechat_string_regcomp (&my_regex, "([0-9]{4})-([0-9]{2})-([0-9]{2})",
                                REG_EXTENDED) == 0)
    {
        string = weechat_string_replace_regex ("date: 2014-02-14", &my_regex,
                                               "$3/$2/$1", '$', NULL, NULL);
        /* string == "date: 14/02/2014" */
        if (string)
            free (string);
        regfree (&my_regex);
    }

注記 | スクリプト API ではこの関数を利用できません。

#### string_translate_chars

WeeChat バージョン 3.8 以上で利用可。

Translate chars in a string.

プロトタイプ:

    char *string_translate_chars (const char *string, const char *chars1, const char *chars2);

引数:

- string: string

- chars1: string with chars to translate

- chars2: string with replacement chars; it must contain the same number of UTF-8 chars than chars1

戻り値:

- string with translated chars, NULL if problem (must be freed by calling "free" after use)

C 言語での使用例:

    /* "test" => "tEst" */
    char *str = weechat_string_translate_chars ("test", "abcdef", "ABCDEF");

    /* "clean the boat" => "CleAn the BoAt" */
    char *str = weechat_string_translate_chars ("clean the boat", "abc", "ABC");

注記 | スクリプト API ではこの関数を利用できません。

#### string_split

WeeChat バージョン 2.5、2.6 で更新。

1 つ以上の区切り文字に従って文字列を分割。

プロトタイプ:

    char **weechat_string_split (const char *string, const char *separators,
                                 const char *strip_items, int flags,
                                 int num_items_max, int *num_items);

引数:

- string: 分割する文字列

- separators: 分割に使う区切り文字

- strip_items: chars to strip from returned items (left/right); optional, can be NULL

- flags: デフォルト動作を変更するビットフラグの組合せ値; 値が 0 の場合、デフォルト動作 (文字列の先頭と末尾にある区切り文字を削除しない、連続する区切り文字を 1 つにまとめない) になります。以下のフラグを組み合わせて値を指定してください:

  - WEECHAT_STRING_SPLIT_STRIP_LEFT: 文字列左端 (先頭) の区切り文字を削除する

  - WEECHAT_STRING_SPLIT_STRIP_RIGHT: 文字列右端 (末尾) の区切り文字を削除する

  - WEECHAT_STRING_SPLIT_COLLAPSE_SEPS: 連続する区切り文字を 1 つにまとめる

  - WEECHAT_STRING_SPLIT_KEEP_EOL: 分割後の各値は分割位置先頭から文字列の最後までとする

- num_items_max: 分割回数の上限 (0 = 制限なし)

- num_items: 分割回数を返す整数型変数へのポインタ

注記 | WeeChat バージョン 2.4 以下で keep_eol とされていた引数は現在 flags 引数に変わられました。両引数の値の対応関係は以下の通りです:

keep_eol | flags
--- | ---
0 | WEECHAT_STRING_SPLIT_STRIP_LEFT | WEECHAT_STRING_SPLIT_STRIP_RIGHT | WEECHAT_STRING_SPLIT_COLLAPSE_SEPS
1 | WEECHAT_STRING_SPLIT_STRIP_LEFT | WEECHAT_STRING_SPLIT_STRIP_RIGHT | WEECHAT_STRING_SPLIT_COLLAPSE_SEPS | WEECHAT_STRING_SPLIT_KEEP_EOL
2 | WEECHAT_STRING_SPLIT_STRIP_LEFT | WEECHAT_STRING_SPLIT_COLLAPSE_SEPS | WEECHAT_STRING_SPLIT_KEEP_EOL

戻り値:

- 文字列の配列、分割に失敗した場合は NULL (使用後には必ず string_free_split を呼び出して領域を開放してください)

C 言語での使用例:

    char **argv;
    int argc;

    argv = weechat_string_split ("abc de  fghi ", " ", NULL, 0, 0, &argc);
    /* result: argv[0] == "abc"
               argv[1] == "de"
               argv[2] == ""
               argv[3] == "fghi"
               argv[4] == ""
               argv[5] == NULL
               argc == 5
    */
    weechat_string_free_split (argv);

    argv = weechat_string_split ("abc de  fghi ", " ", NULL,
                                 WEECHAT_STRING_SPLIT_STRIP_LEFT
                                 | WEECHAT_STRING_SPLIT_STRIP_RIGHT
                                 | WEECHAT_STRING_SPLIT_COLLAPSE_SEPS,
                                 0, &argc);
    /* result: argv[0] == "abc"
               argv[1] == "de"
               argv[2] == "fghi"
               argv[3] == NULL
               argc == 3
    */
    weechat_string_free_split (argv);

    argv = weechat_string_split ("abc de  fghi ", " ", NULL,
                                 WEECHAT_STRING_SPLIT_STRIP_LEFT
                                 | WEECHAT_STRING_SPLIT_STRIP_RIGHT
                                 | WEECHAT_STRING_SPLIT_COLLAPSE_SEPS
                                 | WEECHAT_STRING_SPLIT_KEEP_EOL,
                                 0, &argc);
    /* result: argv[0] == "abc de  fghi"
               argv[1] == "de  fghi"
               argv[2] == "fghi"
               argv[3] == NULL
               argc == 3
    */
    weechat_string_free_split (argv);

    argv = weechat_string_split ("abc de  fghi ", " ", NULL,
                                 WEECHAT_STRING_SPLIT_STRIP_LEFT
                                 | WEECHAT_STRING_SPLIT_COLLAPSE_SEPS
                                 | WEECHAT_STRING_SPLIT_KEEP_EOL,
                                 0, &argc);
    /* result: argv[0] == "abc de  fghi "
               argv[1] == "de  fghi "
               argv[2] == "fghi "
               argv[3] == NULL
               argc == 3
    */
    weechat_string_free_split (argv);

    argv = weechat_string_split (" abc, de,, fghi ", ",", " ",
                                 WEECHAT_STRING_SPLIT_STRIP_LEFT
                                 | WEECHAT_STRING_SPLIT_STRIP_RIGHT
                                 | WEECHAT_STRING_SPLIT_COLLAPSE_SEPS,
                                 0, &argc);
    /* result: argv[0] == "abc"
               argv[1] == "de"
               argv[2] == "fghi"
               argv[3] == NULL
               argc == 3
    */
    weechat_string_free_split (argv);

注記 | スクリプト API ではこの関数を利用できません。

#### string_split_shell

WeeChat バージョン 1.0 以上で利用可。

コマンドを引数を分割する際にシェルがやるように文字列を分割。

This function is a C conversion of Python class "shlex" (file: Lib/shlex.py in Python repository), see this page ↗.

プロトタイプ:

    char **weechat_string_split_shell (const char *string, int *num_items);

引数:

- string: 分割する文字列

- num_items: 分割回数を返す整数型変数へのポインタ

戻り値:

- 文字列の配列、分割に失敗した場合は NULL (使用後には必ず string_free_split を呼び出して領域を開放してください)

C 言語での使用例:

    char **argv;
    int argc;
    argv = weechat_string_split_shell ("test 'first arg'  \"second arg\"", &argc);
    /* result: argv[0] == "test"
               argv[1] == "first arg"
               argv[2] == "second arg"
               argv[3] == NULL
               argc == 3
    */
    weechat_string_free_split (argv);

注記 | スクリプト API ではこの関数を利用できません。

#### string_free_split

文字列分割に使用したメモリを開放。

プロトタイプ:

    void weechat_string_free_split (char **split_string);

引数:

- split_string: 関数 string_split が返した分割文字列の配列

C 言語での使用例:

    char *argv;
    int argc;
    argv = weechat_string_split (string, " ", 0, 0, &argc);
    /* ... */
    weechat_string_free_split (argv);

注記 | スクリプト API ではこの関数を利用できません。

#### string_rebuild_split_string

WeeChat バージョン 3.7 で更新。

Rebuild a string with a split string, using optional separator and index of first/last string to use.

プロトタイプ:

    char *weechat_string_rebuild_split_string (char **split_string,
                                               const char *separator,
                                               int index_start, int index_end);

引数:

- split_string: 関数 string_split が返した分割文字列の配列

- separator: string used to separate strings (can be NULL or empty string)

- index_start: index of first string to use (≥ 0)

- index_end: index of last string to use (must be ≥ index_start; special value -1 can be used to use all arguments until NULL is found)

戻り値:

- 分割文字列から作った文字列 (使用後には必ず "free" を呼び出して領域を開放してください)

C 言語での使用例:

    char **argv;
    int argc;
    argv = weechat_string_split ("abc def ghi", " ", 0, 0, &argc);
    char *str = weechat_string_rebuild_split_string (argv, ";", 0, -1);
    /* str == "abc;def;ghi" */
    /* ... */
    free (str);

注記 | スクリプト API ではこの関数を利用できません。

#### string_split_command

separator でコマンドのリストを分割 (コマンドに区切り文字を使う場合は `\` でエスケープ)。

プロトタイプ:

    char **weechat_string_split_command (const char *command, char separator);

引数:

- command: 分割するコマンド

- separator: 区切り文字

戻り値:

- 文字列の配列、分割に失敗した場合は NULL (使用後には必ず string_free_split_command を呼び出して領域を開放してください)

C 言語での使用例:

    char **argv = weechat_string_split_command ("/command1 arg;/command2", ';');
    /* result: argv[0] == "/command1 arg"
               argv[1] == "/command2"
               argv[2] == NULL
    */
    weechat_free_split_command (argv);

注記 | スクリプト API ではこの関数を利用できません。

#### string_free_split_command

コマンド分割で使用したメモリを開放。

プロトタイプ:

    void weechat_string_free_split_command (char **split_command);

引数:

- split_command: 関数 string_split_command が返す分割コマンドの配列

C 言語での使用例:

    char **argv = weechat_string_split_command ("/command1 arg;/command2", ';');
    /* ... */
    weechat_free_split_command (argv);

注記 | スクリプト API ではこの関数を利用できません。

#### string_format_size

ファイルサイズと設定言語に翻訳された単位を書式に当てはめて文字列を作る

プロトタイプ:

    char *weechat_string_format_size (unsigned long long size);

引数:

- size: サイズ (バイト単位)

戻り値:

- 書式に従う文字列 (使用後には必ず "free" を呼び出して領域を開放してください)

C 言語での使用例:

    /* examples with English locale */

    char *str = weechat_string_format_size (0);  /* str == "0 bytes" */
    /* ... */
    free (str);

    char *str = weechat_string_format_size (1);  /* str == "1 byte" */
    /* ... */
    free (str);

    char *str = weechat_string_format_size (200);  /* str == "200 bytes" */
    /* ... */
    free (str);

    char *str = weechat_string_format_size (15200);  /* str == "15.2 KB" */
    /* ... */
    free (str);

    char *str = weechat_string_format_size (2097152);  /* str == "2.10 MB" */
    /* ... */
    free (str);

スクリプト (Python) での使用例、WeeChat バージョン 2.2 以上で利用可:

    # プロトタイプ
    def string_format_size(size: int) -> str: ...

    # 例
    str = weechat.string_format_size(15200)  # == "15.2 KB"

#### string_parse_size

WeeChat ≥ 3.7.

Parse a string with a size and optional unit and return the size in bytes.

プロトタイプ:

    unsigned long long weechat_string_parse_size (const char *size);

引数:

- size: the size as string: positive integer number followed by optional spaces and optional unit (lower or upper case), which is one of:

  - b: bytes

  - k: kilobytes (1k = 1000 bytes)

  - m: megabytes (1m = 1000k = 1,000,000 bytes)

  - g: gigabytes (1g = 1000m = 1,000,000,000 bytes)

  - t: terabytes (1t = 1000g = 1,000,000,000,000 bytes)

戻り値:

- size in bytes, 0 if error

C 言語での使用例:

    unsigned long long size = weechat_parse_size ("1.34m");  /* size == 1340000 */

Script (Python):

    # プロトタイプ
    def string_parse_size(size: str) -> int: ...

    # 例
    size = weechat.string_parse_size("1.34m")  # 1340000

#### string_color_code_size

WeeChat ≥ 3.0.

Return the size (in bytes) of the WeeChat color code at the beginning of the string.

プロトタイプ:

    int weechat_string_color_code_size (const char *string);

引数:

- string: 文字列

戻り値:

- size (in bytes) of the WeeChat color code at the beginning of the string; if the string is NULL, empty or does not start with a color code, 0 is returned; if the string begins with multiple color codes, only the size of the first one is returned

C 言語での使用例:

    int size;

    size = weechat_string_color_code_size ("test");  /* size == 0 */
    size = weechat_string_color_code_size (weechat_color ("bold"));  /* size == 2 */
    size = weechat_string_color_code_size (weechat_color ("yellow,red"));  /* size == 7 */

スクリプト (Python) での使用例:

    # プロトタイプ
    def string_color_code_size(string: str) -> int: ...

    # 例
    size = weechat.string_color_code_size("test")  # size == 0
    size = weechat.string_color_code_size(weechat.color("bold"))  # size == 2
    size = weechat.string_color_code_size(weechat.color("yellow,red"))  # size == 7

#### string_remove_color

WeeChat バージョン 4.3.0 で更新。

文字列から WeeChat 色コードを削除。

プロトタイプ:

    char *weechat_string_remove_color (const char *string, const char *replacement);

引数:

- string: 文字列

- replacement: if not NULL and not empty, WeeChat color codes are replaced by this string, otherwise WeeChat color codes and following chars (if related to color) are removed from string

戻り値:

- 色コードを削除した文字列 (使用後には必ず "free" を呼び出して領域を開放してください)

C 言語での使用例:

    /* remove color codes */
    char *str = weechat_string_remove_color (my_string1, NULL);
    /* ... */
    free (str);

    /* replace color codes by "?" */
    char *str = weechat_string_remove_color (my_string2, "[color]");
    /* ... */
    free (str);

スクリプト (Python) での使用例:

    # プロトタイプ
    def string_remove_color(string: str, replacement: str) -> str: ...

    # 例
    str = weechat.string_remove_color(my_string, "[color]")

#### string_base_encode

WeeChat ≥ 2.4, updated in 4.3.0.

base 16、32、64 で文字列をエンコード。

プロトタイプ:

    int weechat_string_base_encode (const char *base, const char *from, int length, char *to);

引数:

- base: "16"、"32"、"64"、"64url"

- from: エンコード元文字列

- length: エンコードする文字列の長さ (例えば `strlen(from)`)

- to: エンコード結果を保存する文字列へのポインタ (十分な領域を確保してください、結果はエンコード元文字列よりも長くなります)

戻り値:

- *to に保存された文字列の長さ (最後の `\0` は数えません)、エラー発生時は -1

C 言語での使用例:

    char *string = "abcdefgh", result[128];
    int length;
    length = weechat_string_base_encode ("16", string, strlen (string), result);
    /* length == 16, result == "6162636465666768" */
    length = weechat_string_base_encode ("32", string, strlen (string), result);
    /* length == 16, result == "MFRGGZDFMZTWQ===" */
    length = weechat_string_base_encode ("64", string, strlen (string), result);
    /* length == 12, result == "YWJjZGVmZ2g=" */

注記 | スクリプト API ではこの関数を利用できません。

#### string_base_decode

WeeChat ≥ 2.4, updated in 4.3.0.

base 16、32、64 でエンコードされた文字列をデコード。

プロトタイプ:

    int weechat_string_base_decode (const char *base, const char *from, char *to);

引数:

- base: "16"、"32"、"64"、"64url"

- from: デコード元文字列

- to: デコード結果を保存する文字列へのポインタ (十分な領域を確保してください、結果はデコード元文字列よりも短くなります)

戻り値:

- *to に保存された文字列の長さ (最後の `\0` は数えません)、エラー発生時は -1

C 言語での使用例:

    char result[128];
    int length;
    length = weechat_string_base_decode ("16", "6162636465666768", result);
    /* length == 8, result == "abcdefgh" */
    length = weechat_string_base_decode ("32", "MFRGGZDFMZTWQ===", result);
    /* length == 8, result == "abcdefgh" */
    length = weechat_string_base_decode ("64", "YWJjZGVmZ2g=", result);
    /* length == 8, result == "abcdefgh" */

注記 | スクリプト API ではこの関数を利用できません。

#### string_hex_dump

WeeChat バージョン 1.4 以上で利用可。

16 進数とアスキーバイトを使ってデータのダンプを表示。

プロトタイプ:

    char *string_hex_dump (const char *data, int data_size, int bytes_per_line,
                           const char *prefix, const char *suffix);

引数:

- data: ダンプ対象のデータ

- data_size: data からダンプ対象にするバイト数

- bytes_per_line: 各行に表示するバイト数

- prefix: 各行の先頭に表示するプレフィックス (任意、NULL も可)

- suffix: 各行の末尾に表示するサフィックス (任意、NULL も可)

戻り値:

- データのダンプ表示を含む文字列 (使用後には必ず "free" を呼び出して領域を開放してください)

C 言語での使用例:

    char *string = "abc def-ghi";
    char *dump = weechat_string_hex_dump (string, strlen (string), 8, " >> ", NULL);
    /* dump == " >> 61 62 63 20 64 65 66 2D   a b c   d e f - \n"
               " >> 67 68 69                  g h i           "  */

注記 | スクリプト API ではこの関数を利用できません。

#### string_is_command_char

WeeChat バージョン 0.3.2 以上で利用可。

文字列の 1 文字目がコマンド文字か確認 (デフォルトのコマンド文字は `/`)。

プロトタイプ:

    int weechat_string_is_command_char (const char *string);

引数:

- string: 文字列

戻り値:

- 文字列の 1 文字目がコマンド文字の場合は 1、コマンド文字でない場合は 0

C 言語での使用例:

    int command_char1 = weechat_string_is_command_char ("/test");  /* == 1 */
    int command_char2 = weechat_string_is_command_char ("test");   /* == 0 */

スクリプト (Python) での使用例:

    # プロトタイプ
    def string_is_command_char(string: str) -> int: ...

    # 例
    command_char1 = weechat.string_is_command_char("/test")  # == 1
    command_char2 = weechat.string_is_command_char("test")   # == 0

#### string_input_for_buffer

WeeChat バージョン 0.3.2 以上で利用可。

文字列からバッファに入力される部分に対するポインタを返す ("string" 引数の内部へのポインタ)、コマンドの場合は NULL。

プロトタイプ:

    const char *weechat_string_input_for_buffer (const char *string);

引数:

- string: 文字列

戻り値:

- "string" の内部へのポインタまたは NULL

C 言語での使用例:

    const char *str1 = weechat_string_input_for_buffer ("test");    /* "test"  */
    const char *str2 = weechat_string_input_for_buffer ("/test");   /* NULL    */
    const char *str3 = weechat_string_input_for_buffer ("//test");  /* "/test" */

スクリプト (Python) での使用例:

    # プロトタイプ
    def string_input_for_buffer(string: str) -> str: ...

    # 例
    str1 = weechat.string_input_for_buffer("test")    # "test"
    str2 = weechat.string_input_for_buffer("/test")   # ""
    str3 = weechat.string_input_for_buffer("//test")  # "/test"

#### string_eval_expression

WeeChat ≥ 0.4.0, updated in 0.4.2, 0.4.3, 1.0, 1.1, 1.2, 1.3, 1.6, 1.8, 2.0, 2.2, 2.3, 2.7, 2.9, 3.1, 3.2, 3.3, 3.4, 3.6, 3.8, 4.0.0, 4.2.0, 4.3.0, 4.4.0.

式を評価して文字列として返す。`${variable}` という書式で書かれた特殊変数は展開されます (以下の表を参照)。

注記 | WeeChat バージョン 1.0 以上の場合、入れ子変数を使えるようになりました、例: `${color:${variable}}`。

プロトタイプ:

    char *weechat_string_eval_expression (const char *expr,
                                          struct t_hashtable *pointers,
                                          struct t_hashtable *extra_vars,
                                          struct t_hashtable *options);

引数:

- expr: 評価する式 (条件および変数を参照してください)

- pointers: ポインタを含むハッシュテーブル (キーは文字列、値はポインタ); (現在のウィンドウやバッファへのポインタを持つ) ハッシュテーブルが "window" と "buffer" ポインタを持たない場合はこれらは自動的に追加される (NULL でも可):

  - regex: WeeChat 関数 string_regcomp または regcomp (`man regcomp` を参照) でコンパイル済みの正規表現へのポインタ (regex_t 構造体); このオプションは (以下の) ハッシュテーブル構造体 options メンバの regex とよく似ていますが、より高速に動作します

- extra_vars: 展開される追加変数 (NULL でも可)

- options: いくつかのオプションを含むハッシュテーブル (キーと値は必ず文字列) (NULL でも可):

  - type: デフォルトの挙動では式中の変数をその値で置換するだけですが、この挙動を変更します。設定可能なタイプは以下です:

    - condition: 条件式として式を評価します: 演算子と括弧が使われます、結果はブール値 ("0" または "1") です

  - prefix: 置換する変数のプレフィックス (デフォルト: `${`)

  - suffix: 置換する変数のサフィックス (デフォルト: `}`)

  - extra: デフォルトの挙動では追加変数 (extra_vars) を単純に置換するだけですが、この挙動を変更します。設定可能な値は以下です:

    - eval: 置換前に追加変数 (extra_vars) を評価します (WeeChat バージョン 1.6 以上で利用可)

  - regex: expr のテキストを置換する正規表現 (この場合 expr は評価されません)

  - regex_replace: regex と一緒に使われる置換テキスト、expr に含まれるテキストを置換する (regex_replace は、expr 内で regex 引数にマッチする部分が見つからなくなるまで、毎回評価されます)

  - debug: debug level (string with integer number ≥ 1), if enabled, a key "debug_output" is added in hashtable options:

    - 1: enable debug

    - 2: enable more verbose debug

戻り値:

- 評価された式 (使用後には必ず "free" を呼び出して領域を開放してください)、失敗した場合は NULL (式が不正な場合やメモリが不足している場合)

C 言語での使用例:

    /* 条件式の評価 */
    struct t_hashtable *options1 = weechat_hashtable_new (8,
                                                          WEECHAT_HASHTABLE_STRING,
                                                          WEECHAT_HASHTABLE_STRING,
                                                          NULL,
                                                          NULL);
    weechat_hashtable_set (options1, "type", "condition");
    char *str1 = weechat_string_eval_expression ("${window.win_width} > 100", NULL, NULL, options1);  /* "1" */
    char *str2 = weechat_string_eval_expression ("abc =~ def", NULL, NULL, options1);                 /* "0" */

    /* 単純な展開 */
    char *str3 = weechat_string_eval_expression ("${buffer.full_name}", NULL, NULL, NULL);  /* "core.weechat" */

    /* 正規表現を用いた置換 */
    struct t_hashtable *options2 = weechat_hashtable_new (8,
                                                          WEECHAT_HASHTABLE_STRING,
                                                          WEECHAT_HASHTABLE_STRING,
                                                          NULL,
                                                          NULL);
    /* URL に関するブラックリストを追加 */
    weechat_hashtable_set (options2, "regex", "[a-zA-Z0-9_]+://[^ ]+");
    weechat_hashtable_set (options2, "regex_replace", "[ ${re:0} ]");
    char *str4 = weechat_string_eval_expression ("test: https://weechat.org", NULL, NULL, NULL);  /* "test: [ https://weechat.org ]" */

    /* パスワードを隠す */
    weechat_hashtable_set (options2, "regex", "(password=)([^ ]+)");
    weechat_hashtable_set (options2, "regex_replace", "${re:1}${hide:*,${re:2}}");
    char *str5 = weechat_string_eval_expression ("password=abc password=def", NULL, NULL, NULL);  /* "password=*** password=***" */

スクリプト (Python) での使用例:

    # プロトタイプ
    def string_eval_expression(expr: str, pointers: Dict[str, str], extra_vars: Dict[str, str], options: Dict[str, str]) -> str: ...

    # 例

    # 条件式の評価
    str1 = weechat.string_eval_expression("${window.win_width} > 100", {}, {}, {"type": "condition"})  # "1"
    str2 = weechat.string_eval_expression("abc =~ def", {}, {}, {"type": "condition"})                 # "0"

    # 単純な展開
    str3 = weechat.string_eval_expression("${buffer.full_name}", {}, {}, {}) # "core.weechat"

    # 正規表現を用いた置換: URL に関するブラックリストを追加
    options = {
        "regex": "[a-zA-Z0-9_]+://[^ ]+",
        "regex_replace": "[ ${re:0} ]",
    }
    str4 = weechat.string_eval_expression("test: https://weechat.org", {}, {}, options)  # "test: [ https://weechat.org ]"

    # 正規表現を用いた置換: パスワードを隠す
    options = {
        "regex": "(password=)([^ ]+)",
        "regex_replace": "${re:1}${hide:*,${re:2}}",
    }
    str5 = weechat.string_eval_expression("password=abc password=def", {}, {}, options)  # "password=*** password=***"

##### 条件

条件に使える論理演算子のリスト (上から優先順位の高い順):

演算子 | Min WeeChat | 説明 | 例
--- | --- | --- | ---
`&&` |  | 論理積 | >> `25 && 77` == `1` >> `25 && 0` == `0`
`||` |  | 論理和 | >> `25 || 0` == `1` >> `0 || 0` == `0`

条件に使える比較演算子のリスト (上から優先順位の高い順):

演算子 | Min WeeChat | 説明 | 例
--- | --- | --- | ---
`=~` |  | POSIX 拡張正規表現にマッチ (任意でフラグを指定することも可能です、関数 string_regcomp を確認してください) | >> `abc def =~ ab.*ef` == `1` >> `abc def =~ y.*z` == `0`
`!~` |  | POSIX 拡張正規表現にマッチしない (任意でフラグを指定することも可能です、関数 string_regcomp を確認してください) | >> `abc def !~ ab.*ef` == `0` >> `abc def !~ y.*z` == `1`
`==*` | 2.9 | Is matching mask where "*" is allowed, case-sensitive (see function string_match) | >> `abc def ==* a*f` == `1` >> `abc def ==* y*z` == `0`
`!!*` | 2.9 | Is NOT wildcard mask where "*" is allowed, case-sensitive (see function string_match) | >> `abc def !!* a*f` == `0` >> `abc def !!* y*z` == `1`
`=*` | 1.8 | Is matching mask where "*" is allowed, case-insensitive (see function string_match) | >> `abc def =* A*F` == `1` >> `abc def =* Y*Z` == `0`
`!*` | 1.8 | Is NOT wildcard mask where "*" is allowed, case-insensitive (see function string_match) | >> `abc def !* A*F` == `0` >> `abc def !* Y*Z` == `1`
`==-` | 2.9 | Is included, case-sensitive | >> `abc def ==- bc` == `1` >> `abc def ==- xyz` == `0`
`!!-` | 2.9 | Is NOT included, case-sensitive | >> `abc def !!- bc` == `0` >> `abc def !!- xyz` == `1`
`=-` | 2.9 | Is included, case-insensitive | >> `abc def =- BC` == `1` >> `abc def =- XYZ` == `0`
`!-` | 2.9 | Is NOT included, case-insensitive | >> `abc def !- BC` == `0` >> `abc def !- XYZ` == `1`
`==` |  | 等しい | >> `test == test` == `1` >> `test == string` == `0`
`!=` |  | 等しくない | >> `test != test` == `0` >> `test != string` == `1`
`<=` |  | 以下 | >> `abc <= defghi` == `1` >> `abc <= abc` == `1` >> `defghi <= abc` == `0` >> `15 <= 2` == `0`
`<` |  | より小さい | >> `abc < defghi` == `1` >> `abc < abc` == `0` >> `defghi < abc` == `0` >> `15 < 2` == `0`
`>=` |  | 以上 | >> `defghi >= abc` == `1` >> `abc >= abc` == `1` >> `abc >= defghi` == `0` >> `15 >= 2` == `1`
`>` |  | より大きい | >> `defghi > abc` == `1` >> `abc > abc` == `0` >> `abc > defghi` == `0` >> `15 > 2` == `1`

浮動小数点数として比較される数値表現の書式は以下です:

- 整数 (例: 5、-7)

- 浮動小数点数 (例: 5.2、-7.5、2.83e-2) (WeeChat バージョン 2.0 以上で利用可)

- 16 進数 (例: 0xA3、-0xA3) (WeeChat バージョン 2.0 以上で利用可)

数値表現を二重引用符で括ることで、文字列として比較されます。例:

- `50 > 100` は 0 を返します (数値として比較)

- `"50" > "100"` は 1 を返します (文字列として比較)

##### 変数

式中で展開される変数のリスト (優先度の高い順、展開順の早いものを上に遅いものを下に):

書式 | Min WeeChat | 説明 | 例
--- | --- | --- | ---
`${raw_hl:xxx}` | 4.2.0 | Raw string (not evaluated), with syntax highlighting (using colors). | >> `${raw_hl:${cut:1,,${rev:hello}}}` == `${cut:1,,${rev:hello}}` (with colors)
`${raw:xxx}` | 3.1 | Raw string (not evaluated). | >> `${raw:${info:version}}` == `${info:version}`
`${hl:xxx}` | 4.2.0 | String with syntax highlighting (using colors). | >> `${hl:${file.section.option}}` == `test ${variable}` (with colors)
`${name}` | 3.4 | User variable (defined with `${define:name,value}`). | >> `${name}` == `value`
`${name}` |  | extra_vars の変数 `name` の値に展開 | >> `${name}` == `value`

`${weechat_xxx_dir}`

3.2

A WeeChat directory: `${weechat_config_dir}`, `${weechat_data_dir}`, `${weechat_state_dir}`, `${weechat_cache_dir}` or `${weechat_runtime_dir}`.

>> `${weechat_config_dir}`
== `/home/user/.config/weechat`
>> `${weechat_data_dir}`
== `/home/user/.local/share/weechat`
>> `${weechat_state_dir}`
== `/home/user/.local/state/weechat`
>> `${weechat_cache_dir}`
== `/home/user/.cache/weechat`
>> `${weechat_runtime_dir}`
== `/run/user/1000/weechat`

`${eval:xxx}` | 1.3 | 評価する文字列 | >> `${eval:${date:${weechat.look.buffer_time_format}}}` == `19:02:45` (1) (1) オプション weechat.look.buffer_time_format 内に色コードが存在する場合色付き
`${eval_cond:xxx}` | 3.1 | String to evaluate as condition. | >> `${eval_cond:${window.win_width} > 100}` == `1`
`${esc:xxx}` `${\xxx}` | 1.0 | エスケープ文字を含む文字列 | >> `${esc:prefix\tmessage}` == `prefix<TAB>message` >> `${\ua9}` == `©`

`${chars:range}`

3.8

String with a range of chars, where `range` is one of:
- `digit` (`0123456789`)
- `xdigit` (`0123456789abcdefABCDEF`)
- `lower` (all lower case letters)
- `upper` (all upper case letters)
- `alpha` (all letters)
- `alnum` (all letters and digits)
- a range of chars with format `c1-c2` (`c1` code point must be lower or equal to `c2`)

>> `${chars:digit}`
== `0123456789`
>> `${chars:xdigit}`
== `0123456789abcdefABCDEF`
>> `${chars:lower}`
== `abcdefghijklmnopqrstuvwxyz`
>> `${chars:J-V}`
== `JKLMNOPQRSTUV`
>> `${chars:←-↓}`
== `←↑→↓`

`${lower:string}` | 3.6 | String converted to lower case. | >> `${lower:TEST}` == `test`
`${upper:string}` | 3.6 | String converted to upper case. | >> `${upper:test}` == `TEST`
`${hide:x,string}` | 1.1 | 隠す文字を含むテキスト (`string` に含まれる文字をすべて `x` で置換) | >> `${hide:*,password}` == `********`
`${cut:max,suffix,string}` `${cut:+max,suffix,string}` | 1.8 | `string` の先頭 `max` 文字とオプションの `suffix` 文字 (`string` の文字数が `max` 文字を超える場合) `+max` を使った場合、`max` 文字にはサフィックスの文字数も含まれます。 | >> `${cut:4,…,this is a test}` == `this…` >> `${cut:+4,…,this is a test}` == `t…` >> `${cut:2,>>,こんにちは世界}` == `こん>>`
`${cutscr:max,suffix,string}` `${cutscr:+max,suffix,string}` | 1.8 | `string` の先頭 `max` 文字 (半角文字幅換算) とオプションの `suffix` 文字 (`string` の文字数が `max` 文字を超える場合) `+max` を使った場合、`max` 文字にはサフィックスの文字数も含まれます。 | >> `${cutscr:4,…,this is a test}` == `this…` >> `${cutscr:+4,…,this is a test}` == `thi…` >> `${cutscr:2,>>,こんにちは世界}` == `こ>>`
`${rev:xxx}` | 2.2 | Reversed string (color codes are reversed, so the string should not contain color codes). | >> `${rev:Hello, world!}` == `!dlrow ,olleH` >> `${rev:Hello, ${color:red}world!}` == `!dlrow30F ,olleH` (1) (1) No color, the color code is reversed
`${revscr:xxx}` | 2.7 | Reversed string for screen, color codes are not reversed. | >> `${revscr:Hello, world!}` == `!dlrow ,olleH` >> `${revscr:Hello, ${color:red}world!}` == `!dlrow ,olleH` (1) (1) `,olleH` in red
`${repeat:count,string}` | 2.3 | 繰り返し文字列。 | >> `${repeat:5,-}` == `-----`
`${length:xxx}` | 2.7 | Length of string (number of UTF-8 chars), color codes are ignored. | >> `${length:test}` == `4` >> `${length:こんにちは世界}` == `7`
`${lengthscr:xxx}` | 2.7 | Length of string displayed on screen, color codes are ignored. | >> `${lengthscr:test}` == `4` >> `${lengthscr:こんにちは世界}` == `14`

`${split:number,seps,flags,xxx}`

3.3

Split string, and return, according to `number`:
- `count`: the number of items after split
- `random`: a random item
- integer ≥ 1: the item by index (1 = first item)
- integer ≤ -1: the item by index from the end (-1 = last item, -2 = penultimate item, etc.),
`seps` is a list of chars that are used as separators (if empty, a comma is used),
`flags` is a list of flags separated by `+`:
- `strip_left`: strip separators on the left (beginning of string)
- `strip_right`: strip separators on the right (end of string)
- `collapse_seps`: collapse multiple consecutive separators into a single one
- `keep_eol`: keep end of line for each value
- `strip_items=xyz`: strip chars `x`, `y` and `z` from beginning/end of items
- `max_items=N`: return max N items

>> `${split:1,,,abc,def,ghi}`
== `abc`
>> `${split:-1,,,abc,def,ghi}`
== `ghi`
>> `${split:count,,,abc,def,ghi}`
== `3`
>> `${split:random,,,abc,def,ghi}`
== `def`
>> `${split:3,,collapse_seps,abc,,,def,,,ghi}`
== `ghi`
>> `${split:3,,strip_items=-_,_-abc-_,_-def-_,_-ghi-_}`
== `ghi`
>> `${split:2, ,,this is a test}`
== `is`
>> `${split:2, ,strip_left+strip_right, this is a test }`
== `is`
>> `${split:2, ,keep_eol,this is a test}`
== `is a test`

`${split_shell:number,xxx}`

3.3

Split shell arguments, and return, according to `number`:
- `count`: the number of arguments after split
- `random`: a random argument
- integer ≥ 1: the argument by index (1 = first argument)
- integer ≤ -1: the argument by index from the end (-1 = last argument, -2 = penultimate argument, etc.)

>> `${split_shell:1,"first arg" arg2}`
== `first arg`
>> `${split_shell:-1,"first arg" arg2}`
== `arg2`
>> `${split_shell:count,"first arg" arg2}`
== `2`
>> `${split_shell:random,"first arg" arg2}`
== `arg2`

`${re:xxx}` | 1.1 | Regex data: `0` = whole string matching, `1` to `99` = group captured, `+` = last group captured, `#` = index of last group captured (WeeChat ≥ 1.8), `repl_index` = index of replacement being done (starts to 1) (WeeChat ≥ 3.3). | >> `${re:0}` == `test1 test2` >> `${re:1}` == `test1` >> `${re:2}` == `test2` >> `${re:+}` == `test2` >> `${re:#}` == `2` >> `${re:repl_index}` == `1`
`${color:name}` | 0.4.2 | WeeChat 色コード (色名部分はオプション属性をとることも可能です), 書式を確認するには関数 color をご確認ください | >> `${color:red}red text` == `red text` (1) >> `${color:*214}bold orange text` == `bold orange text` (2) (1) 赤色で (2) 太字オレンジ色で
`${modifier:name,data,string}` | 2.7 | Result of a modifier, see function hook_modifier_exec. | >> `${modifier:eval_path_home,,~}` == `/home/user` >> `${modifier:eval_path_home,directory=config,%h/irc.conf}` == `/home/user/.config/weechat/irc.conf`
`${info:name}` `${info:name,arguments}` | 0.4.3 | WeeChat またはプラグインのインフォ、info_get を参照 | >> `${info:version}` == `1.0` >> `${info:nick_color_name,foo}` == `lightblue`
`${base_encode:base,xxx}` | 2.9 | String encoded in base 16, 32 or 64. | >> `${base_encode:16,test string}` == `7465737420737472696E67` >> `${base_encode:32,test string}` == `ORSXG5BAON2HE2LOM4======` >> `${base_encode:64,test string}` == `dGVzdCBzdHJpbmc=`
`${base_decode:base,xxx}` | 2.9 | String decoded from base 16, 32 or 64. | >> `${base_decode:16,7465737420737472696E67}` == `test string` >> `${base_decode:32,ORSXG5BAON2HE2LOM4======}` == `test string` >> `${base_decode:64,dGVzdCBzdHJpbmc=}` == `test string`
`${date}` `${date:xxx}` | 1.3 | 現在の日付/時刻、カスタム書式を使うことも可能です (see function util_strftimeval)、 デフォルト書式は `%F %T` | >> `${date}` == `2015-06-30 19:02:45` >> `${date:%H:%M:%S}` == `19:02:45` >> `${date:%!.%.3}` == `1435683765.482`
`${env:NAME}` | 1.2 | 環境変数 `NAME` の値 | >> `${env:HOME}` == `/home/user`
`${if:condition}` `${if:condition?true}` `${if:condition?true:false}` | 1.8 | 条件、条件が真の場合の値 (任意)、条件が偽の場合の値 (任意) からなる三項演算子。値を指定しなかった場合、条件の評価結果に応じて "1" または "0" が返されます | >> `${if:${info:term_width}>80?big:small}` == `big`

`${calc:xxx}`

2.7

Result of expression, where parentheses and the following operators are supported:
`+`: addition
`-`: subtraction
`*`: multiplication
`/`: division
`//`: result of division without fractional part
`%`: remainder of division
`**`: power.

>> `${calc:5+2*3}`
== `11`
>> `${calc:(5+2)*3}`
== `21`
>> `${calc:10/4}`
== `2.5`
>> `${calc:10//4}`
== `2`
>> `${calc:9.2%3}`
== `0.2`
>> `${calc:2**16}`
== `65536`

`${random:min,max}` | 3.3 | Random integer number in the range from `min` to `max` (inclusive). | >> `${random:0,10}` == `3`
`${translate:xxx}` | 3.2 | Translated string (depends on the language used by WeeChat to display messages). | >> `${translate:Plugin}` == `Extension` (1) (1) Example in French
`${define:name,value}` | 3.4 | Define a variable `name` set to `value`, which can then be used in the same evaluated expression with `${name}`. | >> `${define:len,${calc:5+3}}${len}x${len}` == `8x8`
`${hdata_count:name[list]}` `${hdata_count:name[pointer]}` | 4.4.0 | Number of items in a hdata list or starting at `pointer`. | >> `${hdata_count:buffer[gui_buffers]}` == `15`
`${sec.data.name}` |  | セキュアデータ `name` の値 | >> `${sec.data.libera_pass}` == `my_password`
`${file.section.option}` |  | オプションの値 | >> `${weechat.look.buffer_time_format}` == `%H:%M:%S`
`${name}` |  | バッファに対するローカル変数 `name` の値 | >> `${nick}` == `FlashCode`
`${pointer}` |  | pointers の変数 `pointer` の値に展開 | >> `${buffer}` == `0x1234abcd`

`${hdata.var1.var2...}`
`${hdata[list].var1.var2...}`

hdata の値 (`window` と `buffer` ポインタはデフォルトで現在のウィンドウ/バッファに設定されます), `list` can be a list name (example: "gui_buffers"), a pointer (example: "0x1234abcd") or a pointer name (example: "my_pointer").
When `var1` is a hashtable, methods `keys()`, `values()`, `keys_sorted()`, `keys_values()` and `keys_values_sorted()` can be called.

>> `${buffer[gui_buffers].full_name}`
== `core.weechat`
>> `${buffer[my_buffer_pointer].full_name}`
== `core.weechat`
>> `${window.buffer.number}`
== `1`
>> `${buffer.local_variables.keys_values()}`
== `plugin:core,name:weechat`
>> `${buffer.local_variables.plugin}`
== `core`

#### string_dyn_alloc

WeeChat バージョン 1.8 以上で利用可

可変長の動的文字列を確保します。
内部では、文字列ポインタ、確保されたサイズ、現在の文字列長の情報からなる構造体が確保されます。

すべての string_dyn_* 関数は文字列ポインタへのポインタ (**string) のみを使います。

プロトタイプ:

    char **weechat_string_dyn_alloc (int size_alloc);

引数:

- size_alloc: 初期確保サイズ (必ずゼロより大きい値を指定してください)

戻り値:

- 動的文字列へのポインタ

C 言語での使用例:

    char **string = weechat_string_dyn_alloc (256);

注記 | スクリプト API ではこの関数を利用できません。

#### string_dyn_copy

WeeChat バージョン 1.8 以上で利用可

動的文字列内に文字列をコピーします。

文字列が再確保された場合 (文字列をコピーするのに十分なサイズが確保されていなかった場合) にはポインタ *string が変わる可能性があります。

プロトタイプ:

    int weechat_string_dyn_copy (char **string, const char *new_string);

引数:

- string: 動的文字列へのポインタ

- new_string: コピーする文字列

戻り値:

- 成功した場合は 1、失敗した場合は 0

C 言語での使用例:

    char **string = weechat_string_dyn_alloc (256);
    if (weechat_string_dyn_copy (string, "test"))
    {
        /* 成功 */
    }
    else
    {
        /* 失敗 */
    }

注記 | スクリプト API ではこの関数を利用できません。

#### string_dyn_concat

WeeChat バージョン 1.8 以上で利用可, updated in 3.0

動的文字列に文字列を連結します。

文字列が再確保された場合 (文字列を連結するのに十分なサイズが確保されていなかった場合) にはポインタ *string が変わる可能性があります。

プロトタイプ:

    int weechat_string_dyn_concat (char **string, const char *add, int bytes);

引数:

- string: 動的文字列へのポインタ

- add: 連結する文字列

- bytes: max number of bytes in add to concatenate, must be lower or equal to length of add (-1 = automatic: concatenate whole string add) (WeeChat ≥ 3.0)

戻り値:

- 成功した場合は 1、失敗した場合は 0

C 言語での使用例:

    char **string = weechat_string_dyn_alloc (256);
    if (weechat_string_dyn_copy (string, "test"))
    {
        if (weechat_string_dyn_concat (string, "abc", -1))
        {
            /* ... */
        }
    }

注記 | スクリプト API ではこの関数を利用できません。

#### string_dyn_free

WeeChat バージョン 1.8 以上で利用可

動的文字列を解放します。

プロトタイプ:

    char *weechat_string_dyn_free (char **string, int free_string);

引数:

- string: 動的文字列へのポインタ

- free_string: 文字列の解放; 0 を指定することで、この関数を呼び出した後でも *string が指すアドレスのメモリを確保したままにできます。

戻り値:

- free_string が 0 の場合には文字列ポインタ、それ以外の場合は NULL

C 言語での使用例:

    char **string = weechat_string_dyn_alloc (256);
    if (weechat_string_dyn_concat (string, "test"))
    {
        /* 成功 */
    }
    else
    {
        /* 失敗 */
    }
    /* ... */
    weechat_string_dyn_free (string, 1);

注記 | スクリプト API ではこの関数を利用できません。

#### string_concat

WeeChat ≥ 4.2.0.

Concatenate multiple strings using a separator.

プロトタイプ:

    const char *weechat_string_concat (const char *separator, ...);

引数:

- separator: the separator string which is inserted between concatenated strings (can be NULL or empty string)

注記 | Last argument MUST always be NULL. A macro called `WEECHAT_STR_CONCAT` can be used, where the final NULL value is not needed (usage of this macro is recommended).

戻り値:

- concatenated string

C 言語での使用例:

    const char *result = weechat_string_concat (" / ", "abc", "def", "ghi", NULL);  /* result == "abc / def / ghi" */

    /* with macro */
    const char *result = WEECHAT_STR_CONCAT(" / ", "abc", "def", "ghi");  /* result == "abc / def / ghi" */

注記 | スクリプト API ではこの関数を利用できません。

### 3.4. UTF-8

UTF-8 文字列関数。

#### utf8_has_8bits

文字列に 8 ビット文字が含まれているか確認。

プロトタイプ:

    int weechat_utf8_has_8bits (const char *string);

引数:

- string: 文字列

戻り値:

- 文字列に 8 ビット文字が含まれる場合は 1、7 ビット文字だけの場合は 0

C 言語での使用例:

    if (weechat_utf8_has_8bits (string))
    {
        /* ... */
    }

注記 | スクリプト API ではこの関数を利用できません。

#### utf8_is_valid

WeeChat バージョン 1.4 で更新。

文字列が妥当な UTF-8 表現か確認。

プロトタイプ:

    int weechat_utf8_is_valid (const char *string, int length, char **error);

引数:

- string: 文字列

- length: 確認する UTF-8 文字の最大文字数; これを 0 以下に設定した場合、文字列中のすべての文字を確認します (WeeChat バージョン 1.4 以上で利用可)

- error: NULL でない場合は *error は文字列に含まれる最初の妥当でない UTF-8 文字へのポインタ

戻り値:

- 妥当な UTF-8 文字列の場合は 1、妥当でない場合は 0

C 言語での使用例:

    char *error;
    if (weechat_utf8_is_valid (string, -1, &error))
    {
        /* ... */
    }
    else
    {
        /* "error" points to first invalid char */
    }

注記 | スクリプト API ではこの関数を利用できません。

#### utf8_normalize

UTF-8 文字列を正規化: 非 UTF-8 文字を削除し、これらを文字で置換。

プロトタイプ:

    void weechat_utf8_normalize (char *string, char replacement);

引数:

- string: 文字列

- replacement: 非 UTF-8 文字を置き換える文字

C 言語での使用例:

    weechat_utf8_normalize (string, '?');

注記 | スクリプト API ではこの関数を利用できません。

#### utf8_prev_char

WeeChat バージョン 1.3 で更新。

文字列中の 1 つ前の UTF-8 文字へのポインタを返す。

プロトタイプ:

    const char *weechat_utf8_prev_char (const char *string_start,
                                        const char *string);

引数:

- string_start: 文字列の開始位置へのポインタ (関数はこのポインタよりも前の文字を返しません)

- string: 文字列へのポインタ (必ず string_start 以上の値)

戻り値:

- 1 つ前の UTF-8 文字へのポインタ、見つからなければ (文字列の開始位置に到達した場合は) NULL (WeeChat バージョン 1.3 以上の場合: 返されるポインタは const char * であり、char * ではありません)

C 言語での使用例:

    const char *prev_char = weechat_utf8_prev_char (string, ptr_in_string);

注記 | スクリプト API ではこの関数を利用できません。

#### utf8_next_char

WeeChat バージョン 1.3 で更新。

文字列中の 1 つ後の UTF-8 文字へのポインタを返す。

プロトタイプ:

    const char *weechat_utf8_next_char (const char *string);

引数:

- string: 文字列

戻り値:

- 1 つ後の UTF-8 文字へのポインタ、見つからなければ (文字列の最後に到達した場合は) NULL (WeeChat バージョン 1.3 以上の場合: 返されるポインタは const char * であり、char * ではありません)

C 言語での使用例:

    const char *next_char = weechat_utf8_next_char (string);

注記 | スクリプト API ではこの関数を利用できません。

#### utf8_char_int

UTF-8 文字を整数で返す。

プロトタイプ:

    int weechat_utf8_char_int (const char *string);

引数:

- string: 文字列

戻り値:

- UTF-8 文字の整数表現

C 言語での使用例:

    int char_int = weechat_utf8_char_int ("être");  /* "ê" as integer */

注記 | スクリプト API ではこの関数を利用できません。

#### utf8_char_size

UTF-8 文字のサイズを返す (バイト単位)。

プロトタイプ:

    int weechat_utf8_char_size (const char *string);

引数:

- string: 文字列

戻り値:

- UTF-8 文字のサイズ (バイト単位)

C 言語での使用例:

    int char_size = weechat_utf8_char_size ("être");  /* == 2 */

注記 | スクリプト API ではこの関数を利用できません。

#### utf8_strlen

UTF-8 文字の長さを返す (UTF-8 文字の個数)。

プロトタイプ:

    int weechat_utf8_strlen (const char *string);

引数:

- string: 文字列

戻り値:

- UTF-8 文字列の長さ (UTF-8 文字の個数)

C 言語での使用例:

    int length = weechat_utf8_strlen ("chêne");  /* == 5 */

注記 | スクリプト API ではこの関数を利用できません。

#### utf8_strnlen

文字列の bytes バイト目までに含まれる UTF-8 文字列の長さを返す (UTF-8 文字の個数)。

プロトタイプ:

    int weechat_utf8_strnlen (const char *string, int bytes);

引数:

- string: 文字列

- bytes: バイト数の上限

戻り値:

- UTF-8 文字列の長さ (UTF-8 文字の個数)

C 言語での使用例:

    int length = weechat_utf8_strnlen ("chêne", 4);  /* == 3 */

注記 | スクリプト API ではこの関数を利用できません。

#### utf8_strlen_screen

UTF-8 文字列を画面上に表示するために必要な画面幅を返す。

プロトタイプ:

    int weechat_utf8_strlen_screen (const char *string);

引数:

- string: 文字列

戻り値:

- UTF-8 文字列を画面上に表示するために必要な画面幅。

C 言語での使用例:

    int length_on_screen = weechat_utf8_strlen_screen ("é");  /* == 1 */

注記 | スクリプト API ではこの関数を利用できません。

#### utf8_char_size_screen

WeeChat バージョン 3.8 で更新。

UTF-8 文字を画面上に表示するために必要な画面幅を返す。

プロトタイプ:

    int weechat_utf8_char_size_screen (const char *string);

引数:

- string: 文字列

戻り値:

- UTF-8 文字を画面上に表示するために必要な画面幅:

  - -1: non printable char

  - ≥ 0: printable char

The result is the return value of function `wcwidth` (see `man wcwidth`), with exception for the following chars, that have a specific behavior in WeeChat:

- U+0009 (Tabulation): value of option weechat.look.tab_width ↗

- U+0001 (1) to U+001F (31), except U+0009 (Tabulation): 1

- U+00AD (173, soft hyphen): -1

- U+200B (8203, zero width space): -1

C 言語での使用例:

    int length_on_screen = weechat_utf8_char_size_screen ("é");  /* == 1 */

注記 | スクリプト API ではこの関数を利用できません。

#### utf8_add_offset

WeeChat バージョン 1.3 で更新。

UTF-8 文字列で N 文字前に進む。

プロトタイプ:

    const char *weechat_utf8_add_offset (const char *string, int offset);

引数:

- string: 文字列

- offset: 文字数

戻り値:

- 文字列の N 文字後に進んだ位置へのポインタ (元文字列の最後より後の位置を指す場合は NULL) (WeeChat バージョン 1.3 以上の場合: 返されるポインタは const char * であり、char * ではありません)

C 言語での使用例:

    const char *str = "chêne";
    const char *str2 = weechat_utf8_add_offset (str, 3);  /* points to "ne" */

注記 | スクリプト API ではこの関数を利用できません。

#### utf8_real_pos

UTF-8 文字列中の真の位置を返す。

プロトタイプ:

    int weechat_utf8_real_pos (const char *string, int pos);

引数:

- string: 文字列

- pos: 位置 (文字目)

戻り値:

- 真の位置 (バイト目)

C 言語での使用例:

    int pos = weechat_utf8_real_pos ("chêne", 3);  /* == 4 */

注記 | スクリプト API ではこの関数を利用できません。

#### utf8_pos

UTF-8 文字列中の位置を返す。

プロトタイプ:

    int weechat_utf8_pos (const char *string, int real_pos);

引数:

- string: 文字列

- real_pos: 真の位置 (バイト単位)

戻り値:

- 位置 (文字目)

C 言語での使用例:

    int pos = weechat_utf8_pos ("chêne", 4);  /* == 3 */

注記 | スクリプト API ではこの関数を利用できません。

#### utf8_strndup

最長 length 文字の複製された文字列を返す。

プロトタイプ:

    char *weechat_utf8_strndup (const char *string, int length);

引数:

- string: 文字列

- length: 複製する文字数の最大値

戻り値:

- 複製された文字列 (使用後には必ず "free" を呼び出して領域を開放してください)

C 言語での使用例:

    char *string = weechat_utf8_strndup ("chêne", 3);  /* returns "chê" */
    /* ... */
    free (string);

注記 | スクリプト API ではこの関数を利用できません。

#### utf8_strncpy

WeeChat ≥ 3.8.

Copy length chars max in another string and add null byte at the end.

プロトタイプ:

    void weechat_utf8_strncpy (char *dest, const char *string, int length);

引数:

- dest: destination string (must be long enough)

- string: 文字列

- length: max chars to copy

C 言語での使用例:

    char dest[256];

    weechat_utf8_strncpy (dest, "chêne", 3);  /* copies "chê" to dest */

注記 | スクリプト API ではこの関数を利用できません。

### 3.5. Cryptography

Some cryptographic functions.

#### crypto_hash

WeeChat バージョン 2.8 以上で利用可。

Compute hash of data.

プロトタイプ:

    int weechat_crypto_hash (const void *data, int data_size, const char *hash_algo,
                             void *hash, int *hash_size);

引数:

- data: the data to hash

- data_size: number of bytes to hash in data

- hash_algo: the hash algorithm, see table below

- hash: pointer to the hash variable, which is used to store the resulting hash (the buffer must be large enough, according to the algorithm, see table below)

- hash_size: pointer to a variable used to store the length of the hash computed (in bytes) (can be NULL)

Supported hash algorithms:

Value | Algorithm | Hash size | Notes
--- | --- | --- | ---
`crc32` | CRC32 | 4 bytes (32 bits) | Not a hash algorithm in the cryptographic sense.
`md5` | MD5 | 16 bytes (128 bits) | Weak, not recommended for cryptography usage.
`sha1` | SHA-1 | 20 bytes (160 bits) | Weak, not recommended for cryptography usage.
`sha224` | SHA-224 | 28 bytes (224 bits) |
`sha256` | SHA-256 | 32 bytes (256 bits) |
`sha384` | SHA-384 | 48 bytes (384 bits) |
`sha512` | SHA-512 | 64 bytes (512 bits) |
`sha512-224` | SHA-512/224 | 28 bytes (224 bits) | Algorithm available with libgcrypt ≥ 1.9.4.
`sha512-256` | SHA-512/256 | 32 bytes (256 bits) | Algorithm available with libgcrypt ≥ 1.9.4.
`sha3-224` | SHA3-224 | 28 bytes (224 bits) | Algorithm available with libgcrypt ≥ 1.7.0.
`sha3-256` | SHA3-256 | 32 bytes (256 bits) | Algorithm available with libgcrypt ≥ 1.7.0.
`sha3-384` | SHA3-384 | 48 bytes (384 bits) | Algorithm available with libgcrypt ≥ 1.7.0.
`sha3-512` | SHA3-512 | 64 bytes (512 bits) | Algorithm available with libgcrypt ≥ 1.7.0.
`blake2b-160` | BLAKE2B-160 | 20 bytes (160 bits) | Algorithm available with libgcrypt ≥ 1.8.0.
`blake2b-256` | BLAKE2B-256 | 32 bytes (256 bits) | Algorithm available with libgcrypt ≥ 1.8.0.
`blake2b-384` | BLAKE2B-384 | 48 bytes (384 bits) | Algorithm available with libgcrypt ≥ 1.8.0.
`blake2b-512` | BLAKE2B-512 | 64 bytes (512 bits) | Algorithm available with libgcrypt ≥ 1.8.0.
`blake2s-128` | BLAKE2S-128 | 16 bytes (128 bits) | Algorithm available with libgcrypt ≥ 1.8.0.
`blake2s-160` | BLAKE2S-160 | 20 bytes (160 bits) | Algorithm available with libgcrypt ≥ 1.8.0.
`blake2s-224` | BLAKE2S-224 | 28 bytes (224 bits) | Algorithm available with libgcrypt ≥ 1.8.0.
`blake2s-256` | BLAKE2S-256 | 32 bytes (256 bits) | Algorithm available with libgcrypt ≥ 1.8.0.

戻り値:

- 成功した場合は 1、失敗した場合は 0

C 言語での使用例:

    const char *data = "abcdefghijklmnopqrstuvwxyz";
    char hash[256 / 8];
    int rc, hash_size;
    rc = weechat_crypto_hash (data, strlen (data), "sha256", hash, &hash_size);
    /* rc == 1, hash_size == 32 and hash is a buffer with:
       71 c4 80 df 93 d6 ae 2f 1e fa d1 44 7c 66 c9 52 5e 31 62 18 cf 51 fc 8d 9e d8 32 f2 da f1 8b 73 */

注記 | スクリプト API ではこの関数を利用できません。

#### crypto_hash_flie

WeeChat バージョン 3.7 以上で利用可。

Compute hash of a file.

プロトタイプ:

    int weechat_crypto_hash_file (const char *filename, const char *hash_algo,
                                  void *hash, int *hash_size);

引数:

- filename: パスやファイル名

- hash_algo: the hash algorithm, see table in function crypto_hash

- hash: pointer to the hash variable, which is used to store the resulting hash (the buffer must be large enough, according to the algorithm, see table in function crypto_hash)

- hash_size: pointer to a variable used to store the size of the hash computed (in bytes) (can be NULL)

戻り値:

- 成功した場合は 1、失敗した場合は 0

C 言語での使用例:

    char hash[256 / 8];
    int rc, hash_size;
    rc = weechat_crypto_hash_file ("/path/to/file", "sha256", hash, &hash_size);
    /* rc == 1, hash_size == 32 and hash is a buffer with:
       71 c4 80 df 93 d6 ae 2f 1e fa d1 44 7c 66 c9 52 5e 31 62 18 cf 51 fc 8d 9e d8 32 f2 da f1 8b 73 */

注記 | スクリプト API ではこの関数を利用できません。

#### crypto_hash_pbkdf2

WeeChat バージョン 2.8 以上で利用可。

Compute PKCS#5 Passphrase Based Key Derivation Function number 2 (PBKDF2) hash of data.

プロトタイプ:

    int weechat_crypto_hash_pbkdf2 (const void *data, int data_size,
                                    const char *hash_algo,
                                    const void *salt, int salt_size,
                                    int iterations,
                                    void *hash, int *hash_size);

引数:

- data: the data to hash

- data_size: number of bytes to hash in data

- hash_algo: hash algorithm used by the key derivation function, see table in function crypto_hash

- salt: the salt

- salt_size: number of bytes in salt

- iterations: number of iterations

- hash: pointer to the hash variable, which is used to store the resulting hash (the buffer must be large enough, according to the algorithm, see table in function crypto_hash)

- hash_size: pointer to a variable used to store the size of the hash computed (in bytes) (can be NULL)

戻り値:

- 成功した場合は 1、失敗した場合は 0

C 言語での使用例:

    const char *data = "abcdefghijklmnopqrstuvwxyz";
    const char *salt = "12345678901234567890123456789012";  /* 32 bytes */
    char hash[256 / 8];
    int rc, hash_size;
    rc = weechat_crypto_hash_pbkdf2 (data, strlen (data), "sha256", salt, strlen (salt), 100000,
                                     hash, &hash_size);
    /* rc == 1, hash_size == 32 and hash is a buffer with:
       99 b3 5e 42 53 d1 a7 a8 49 c1 dc 2c e2 53 c2 b6 6d a1 8b dc 6e 78 a7 06 e0 ef 34 db 0a 7a a2 bb */

注記 | スクリプト API ではこの関数を利用できません。

#### crypto_hmac

WeeChat バージョン 3.2 以上で利用可。

Compute keyed-hash message authentication code (HMAC).

プロトタイプ:

    int weechat_crypto_hmac (const void *key, int key_size, const void *message, int message_size,
                             int hash_algo, void *hash, int *hash_size);

引数:

- key: the key

- key_size: number of bytes in key

- message: the message

- message_size: number of bytes in message

- hash_algo: the hash algorithm, see table in function crypto_hash

- hash: pointer to the hash variable, which is used to store the resulting hash (the buffer must be large enough, according to the algorithm, see table in function crypto_hash)

- hash_size: pointer to a variable used to store the size of the hash computed (in bytes) (can be NULL)

戻り値:

- 成功した場合は 1、失敗した場合は 0

C 言語での使用例:

    const char *key = "the key";
    const char *message = "the message";
    char hash[256 / 8];
    int rc, hash_size;
    rc = weechat_crypto_hmac (key, strlen (key), message, strlen (message), "sha256", hash, &hash_size);
    /* rc == 1, hash_size == 32 and hash is a buffer with:
       47 36 67 02 fc bc b1 97 a4 25 e6 7a b9 52 92 bd 15 9a 66 91 9c fb 94 b0 b4 9a 39 cb c0 24 2d 7b */

注記 | スクリプト API ではこの関数を利用できません。

### 3.6. ディレクトリ

ディレクトリに関する関数。

#### mkdir_home

WeeChat バージョン 3.2 で更新。

WeeChat ホームディレクトリの下にディレクトリを作成。

プロトタイプ:

    int weechat_mkdir_home (char *directory, int mode);

引数:

- directory: name of directory to create; it can start with one of these strings to force a specific WeeChat directory (WeeChat ≥ 3.2):

  - `${weechat_config_dir}`

  - `${weechat_data_dir}` (default)

  - `${weechat_state_dir}`

  - `${weechat_cache_dir}`

  - `${weechat_runtime_dir}`

- mode: ディレクトリのモード

戻り値:

- ディレクトリの作成に成功した場合は 1、エラーが起きた場合は 0

C 言語での使用例:

    if (!weechat_mkdir_home ("${weechat_cache_dir}/temp", 0755))
    {
        /* error */
    }

スクリプト (Python) での使用例:

    # プロトタイプ
    def mkdir_home(directory: str, mode: int) -> int: ...

    # 例
    weechat.mkdir_home("${weechat_cache_dir}/temp", 0755)

#### mkdir

ディレクトリを作成。

プロトタイプ:

    int weechat_mkdir (char *directory, int mode);

引数:

- directory: 作成するディレクトリの名前

- mode: ディレクトリのモード

戻り値:

- ディレクトリの作成に成功した場合は 1、エラーが起きた場合は 0

C 言語での使用例:

    if (!weechat_mkdir ("/tmp/mydir", 0755))
    {
        /* error */
    }

スクリプト (Python) での使用例:

    # プロトタイプ
    def mkdir(directory: str, mode: int) -> int: ...

    # 例
    weechat.mkdir("/tmp/mydir", 0755)

#### mkdir_parents

ディレクトリの作成と必要に応じて親ディレクトリの作成を行う。

プロトタイプ:

    int weechat_mkdir_parents (char *directory, int mode);

引数:

- directory: 作成するディレクトリの名前

- mode: ディレクトリのモード

戻り値:

- ディレクトリの作成に成功した場合は 1、エラーが起きた場合は 0

C 言語での使用例:

    if (!weechat_mkdir_parents ("/tmp/my/dir", 0755))
    {
        /* error */
    }

スクリプト (Python) での使用例:

    # プロトタイプ
    def mkdir_parents(directory: str, mode: int) -> int: ...

    # 例
    weechat.mkdir_parents("/tmp/my/dir", 0755)

#### exec_on_files

WeeChat バージョン 1.5 と 2.0 で更新。

ディレクトリ中のファイルを探し、各ファイルに対してコールバックを実行。

プロトタイプ:

    void weechat_exec_on_files (const char *directory,
                                int recurse_subdirs,
                                int hidden_files,
                                void (*callback)(void *data,
                                                 const char *filename),
                                void *callback_data);

引数:

- directory: ファイルを検索するディレクトリ

- recurse_subdirs: サブディレクトリ内を再帰的に探す場合は 1 (WeeChat バージョン 2.0 以上で利用可)

- hidden_files: 検索対象に隠しファイルを含める場合は 1、含めない場合は 0

- callback: 各ファイルに対して呼び出すコールバック関数、引数:

  - void *data: ポインタ

  - const char *filename: 見つかったファイルの名前

- callback_data: WeeChat が callback コールバックを呼び出す際にコールバックに渡すポインタ

C 言語での使用例:

    void callback (void *data, const char *filename)
    {
        /* ... */
    }
    ...
    weechat_exec_on_files ("/tmp", 0, 0, &callback, NULL);

注記 | スクリプト API ではこの関数を利用できません。

#### file_get_content

WeeChat バージョン 0.3.1 以上で利用可。

テキストファイルの内容を文字列に代入。

プロトタイプ:

    char *weechat_file_get_content (const char *filename);

引数:

- filename: パスやファイル名

戻り値:

- ファイルの内容を含む文字列 (使用後には必ず "free" を呼び出して領域を開放してください)

C 言語での使用例:

    char *content;

    content = weechat_file_get_content ("/tmp/test.txt");
    /* ... */
    free (content);

注記 | スクリプト API ではこの関数を利用できません。

#### file_copy

WeeChat ≥ 3.3.

Copy a file to another location.

プロトタイプ:

    int weechat_file_copy (const char *from, const char *to);

引数:

- from: source file

- to: destination file

戻り値:

- 1 if OK, 0 if error

C 言語での使用例:

    if (weechat_file_copy ("/tmp/test.txt", "/path/to/test2.txt"))
    {
        /* OK */
    }

注記 | スクリプト API ではこの関数を利用できません。

#### file_compress

WeeChat ≥ 3.7.

Compress a file with gzip or zstd.

プロトタイプ:

    int weechat_file_compress (const char *from, const char *to,
                               const char *compressor, int compression_level);

引数:

- from: source file

- to: destination file

- compressor: the compressor to use, one of:

  - gzip: gzip compression

  - zstd: zstandard compression (available only if zstd was enabled when WeeChat was compiled)

- compression_level: compression level, between 1 (fast, low compression) to 100 (slow, best compression)

戻り値:

- 1 if OK, 0 if error

C 言語での使用例:

    if (weechat_file_compress ("/tmp/test.txt", "/tmp/test.txt.zst", "zstd", 50))
    {
        /* OK */
    }

注記 | スクリプト API ではこの関数を利用できません。

#### file_compare

WeeChat ≥ 4.7.0.

Compare the content of two files.

プロトタイプ:

    int weechat_file_compare (const char *filename1, const char *filename2);

引数:

- filename1: first file to compare

- filename2: second file to compare

戻り値:

- 0: both files have same content

- 1: content is different

- 2: error (file not found or read error)

C 言語での使用例:

    if (weechat_file_compare ("/tmp/test.txt", "/tmp/test2.txt") == 0)
    {
        /* same content */
    }

注記 | スクリプト API ではこの関数を利用できません。

### 3.7. ユーティリティ

便利な関数。

#### util_parse_int

WeeChat ≥ 4.8.0.

Parse an integer number of type "int" in a string.

プロトタイプ:

    int weechat_util_parse_int (const char *string, int base, int *result);

引数:

- string: string to parse

- base: can be 0 (automatic) or an integer between 2 and 36 (inclusive)

- result: pointer to a variable updated if the string is correctly parsed (if pointer is NULL, the number found is not returned)

戻り値:

- 1: OK

- 0: error

The following strings are invalid and the function returns 0:

- empty string

- number with extra non-digits after

- number < INT_MIN (min value for a variable of type "int")

- number > INT_MAX (max value for a variable of type "int")

- invalid integer for the given base

C 言語での使用例:

    int number;
    if (weechat_util_parse_int ("1234", 10, &number))
    {
        /* number == 1234 */
    }
    if (!weechat_util_parse_int ("abc", 10, &number))
    {
        /* parsing error, number is unchanged */
    }

注記 | スクリプト API ではこの関数を利用できません。

#### util_parse_long

WeeChat ≥ 4.8.0.

Parse an integer number of type "long" in a string.

プロトタイプ:

    int weechat_util_parse_long (const char *string, int base, long *result);

引数:

- string: string to parse

- base: can be 0 (automatic) or an integer between 2 and 36 (inclusive)

- result: pointer to a variable updated if the string is correctly parsed (if pointer is NULL, the number found is not returned)

戻り値:

- 1: OK

- 0: error

The following strings are invalid and the function returns 0:

- empty string

- number with extra non-digits after

- number < LONG_MIN (min value for a variable of type "long")

- number > LONG_MAX (max value for a variable of type "long")

- invalid integer for the given base

C 言語での使用例:

    long number;
    if (weechat_util_parse_long ("1234", 10, &number))
    {
        /* number == 1234 */
    }
    if (!weechat_util_parse_long ("abc", 10, &number))
    {
        /* parsing error, number is unchanged */
    }

注記 | スクリプト API ではこの関数を利用できません。

#### util_parse_longlong

WeeChat ≥ 4.8.0.

Parse an integer number of type "long long" in a string.

プロトタイプ:

    int weechat_util_parse_longlong (const char *string, int base, long long *result);

引数:

- string: string to parse

- base: can be 0 (automatic) or an integer between 2 and 36 (inclusive)

- result: pointer to a variable updated if the string is correctly parsed (if pointer is NULL, the number found is not returned)

戻り値:

- 1: OK

- 0: error

The following strings are invalid and the function returns 0:

- empty string

- number with extra non-digits after

- number < LLONG_MIN (min value for a variable of type "long long")

- number > LLONG_MAX (max value for a variable of type "long long")

- invalid integer for the given base

C 言語での使用例:

    long long number;
    if (weechat_util_parse_longlong ("1234", 10, &number))
    {
        /* number == 1234 */
    }
    if (!weechat_util_parse_longlong ("abc", 10, &number))
    {
        /* parsing error, number is unchanged */
    }

注記 | スクリプト API ではこの関数を利用できません。

#### util_timeval_cmp

2 つの "timeval" 構造体を比較。

プロトタイプ:

    int weechat_util_timeval_cmp (struct timeval *tv1, struct timeval *tv2);

引数:

- tv1: 1 番目の "timeval" 構造体

- tv2: 2 番目の "timeval" 構造体

戻り値:

- tv1 < tv2 の場合は -1

- tv1 == tv2 の場合は 0

- tv1 > tv2 の場合は +1

C 言語での使用例:

    if (weechat_util_timeval_cmp (&tv1, &tv2) > 0)
    {
        /* tv1 > tv2 */
    }

注記 | スクリプト API ではこの関数を利用できません。

#### util_timeval_diff

WeeChat バージョン 1.1 で更新。

2 つの "timeval" 構造体の差を返す (マイクロ秒単位)。

プロトタイプ:

    long long weechat_util_timeval_diff (struct timeval *tv1, struct timeval *tv2);

引数:

- tv1: 1 番目の "timeval" 構造体

- tv2: 2 番目の "timeval" 構造体

戻り値:

- マイクロ秒単位の差

注記 | WeeChat バージョン 1.0 以前の場合、戻り値の単位はミリ秒でした。

C 言語での使用例:

    long long diff = weechat_util_timeval_diff (&tv1, &tv2);

注記 | スクリプト API ではこの関数を利用できません。

#### util_timeval_add

WeeChat バージョン 1.1 で更新。

timeval 構造体に時間間隔を追加 (マイクロ秒単位)。

プロトタイプ:

    void weechat_util_timeval_add (struct timeval *tv, long long interval);

引数:

- tv: timeval 構造体

- interval: 時間間隔 (マイクロ秒単位)

注記 | WeeChat バージョン 1.0 以前の場合、時間間隔の単位はミリ秒でした。

C 言語での使用例:

    weechat_util_timeval_add (&tv, 2000000);  /* add 2 seconds */

注記 | スクリプト API ではこの関数を利用できません。

#### util_get_time_string

WeeChat バージョン 0.3.2 以上で利用可、バージョン 1.3 で更新。

日付/時刻を "strftime" で作った文字列として取得します。書式は weechat.look.time_format で定義されています。

プロトタイプ:

    const char *weechat_util_get_time_string (const time_t *date);

引数:

- date: 日付へのポインタ

戻り値:

- 日付/時刻文字列へのポインタ

C 言語での使用例:

    time_t date = time (NULL);
    weechat_printf (NULL, "date: %s",
                    weechat_util_get_time_string (&date));

注記 | スクリプト API ではこの関数を利用できません。

#### util_strftimeval

WeeChat ≥ 4.2.0, updated in 4.3.0, 4.7.0.

Format date and time like function `strftime` in C library, using `struct timeval` as input, and supporting extra specifiers.

Prototype:

    int weechat_util_strftimeval (char *string, int max, const char *format, struct timeval *tv);

Arguments:

- string: buffer where the formatted string is stored

- max: string size

- format: format, the same as strftime function, with these extra specifiers:

  - `%@`: return the date expressed in Coordinated Universal Time (UTC) instead of date relative to the user’s specified timezone (WeeChat ≥ 4.7.0)

  - `%.N` where `N` is between 1 and 6: zero-padded microseconds on N digits (for example `%.3` for milliseconds)

  - `%f`: alias of `%.6`

  - `%!`: timestamp as integer, in seconds (value of tv→tv_sec)

Return value:

- number of bytes put in string (value returned from strftime function)

C example:

    char time[256];
    struct timeval tv;
    gettimeofday (&tv, NULL);
    weechat_util_strftimeval (time, sizeof (time), "%@%FT%T.%fZ", &tv);
    /* result: 2023-12-26T18:10:04.460509Z */

注記 | スクリプト API ではこの関数を利用できません。

#### util_parse_time

WeeChat ≥ 4.2.0, updated in 4.8.0.

Parse date/time with support of microseconds.

Prototype:

    int util_parse_time (const char *datetime, struct timeval *tv);

Arguments:

- date: date/time (see supported formats below)

- tv: parsed date/time ("timeval" structure)

Supported date/time format (supposing the current time is `2025-08-30 21:04:55` (Europe/Paris), so with timezone offset `+02:00`, UTC time being `19:04:55`):

Format | Examples
--- | ---
Date (midnight) | `2025-08-30`
ISO 8601, date + local time | `2025-08-30T21:04:55 2025-08-30T21:04:55.123456`
ISO 8601, date + local time + offset | `2025-08-30T16:04:55-03 2025-08-30T16:04:55-0300 2025-08-30T21:04:55+0200 2025-08-30T21:04:55+02:00 2025-08-30T21:04:55.123456+0200`
ISO 8601, date + UTC time | `2025-08-30T19:04:55Z 2025-08-30T19:04:55.123456Z`
RFC 3339, date + local time | `2025-08-30 21:04:55 2025-08-30 21:04:55.123456`
RFC 3339, date + local time + offset | `2025-08-30 16:04:55-03 2025-08-30 16:04:55-0300 2025-08-30 21:04:55+0200 2025-08-30 21:04:55 +0200 2025-08-30 21:04:55+02:00 2025-08-30 21:04:55 +02:00 2025-08-30 21:04:55.123456+0200 2025-08-30 21:04:55.123456 +02:00`
RFC 3339, date + UTC time | `2025-08-30 19:04:55Z 2025-08-30 19:04:55.123456Z`
Local time | `21:04:55 21:04:55.123456`
Local time + offset | `16:04:55-03 16:04:55-0300 21:04:55+0200 21:04:55 +0200 21:04:55+02:00 21:04:55 +02:00 21:04:55.123456+0200 21:04:55.123456 +02:00`
UTC time | `19:04:55Z 19:04:55.123456Z`
Timestamp date | `1756580695 1756580695.123456 1756580695,123456`

Notes:

- For ISO 8601, the separator between date and time is `T` (upper case) or `t` (lower case).

- For UTC time, the final char is `Z` (upper case) or `z` (lower case).

- The timezone offset format is one of:

  - `[+/-]hh:mm` (hours and minutes)

  - `[+/-]hhmm` (hours and minutes)

  - `[+/-]hh` (hours).

- Precision after seconds can be from one-tenth of second (1 digit, for example `21:04:55.1`) to one microsecond (6 digits, for example `21:04:55.123456`).
  A dot (`.`) or comma (`,`) can separate seconds from the other digits.

Return value:

- 1 if OK, 0 if error

C examples:

    struct timeval tv;

    weechat_util_parse_time ("2025-08-30T19:04:55.123456Z", &tv);  /* == 1 */
    /* result: tv.tv_sec == 1756580695, tv.tv_usec = 123456 */

    weechat_util_parse_time ("2025-08-30 21:04:55.123456 +02:00", &tv);  /* == 1 */
    /* same result */

    weechat_util_parse_time ("21:04:55.123456", &tv);  /* == 1 */
    /* same result */

注記 | スクリプト API ではこの関数を利用できません。

#### util_version_number

WeeChat ≥ 0.3.9, updated in 4.7.0.

WeeChat バージョンの文字列を番号に変換。

プロトタイプ:

    unsigned long weechat_util_version_number (const char *version);

引数:

- version: WeeChat バージョン文字列 (例: "0.3.9" や "0.3.9-dev")

C 言語での使用例:

    version_number = weechat_util_version_number ("0.3.8");      /* == 0x00030800 */
    version_number = weechat_util_version_number ("0.3.9-dev");  /* == 0x00030900 */
    version_number = weechat_util_version_number ("0.3.9-rc1");  /* == 0x00030900 */
    version_number = weechat_util_version_number ("0.3.9");      /* == 0x00030900 */
    version_number = weechat_util_version_number ("1.0");        /* == 0x01000000 */
    version_number = weechat_util_version_number ("4.0.0");      /* == 0x04000000 */

注記 | スクリプト API ではこの関数を利用できません。

### 3.8. ソート済みリスト

ソート済みリスト関数。

#### list_new

新しいリストを作成。

プロトタイプ:

    struct t_weelist *weechat_list_new ();

戻り値:

- 新しいリストへのポインタ

C 言語での使用例:

    struct t_weelist *list = weechat_list_new ();

スクリプト (Python) での使用例:

    # プロトタイプ
    def list_new() -> str: ...

    # 例
    list = weechat.list_new()

#### list_add

リストに要素を追加。

プロトタイプ:

    struct t_weelist_item *weechat_list_add (struct t_weelist *weelist,
                                             const char *data,
                                             const char *where,
                                             void *user_data);

引数:

- weelist: リストへのポインタ

- data: リストに追加するデータ

- where: データを追加する場所:

  - WEECHAT_LIST_POS_SORT: リストに追加、リストをソートされた状態を保持

  - WEECHAT_LIST_POS_BEGINNING: リストの最初に追加

  - WEECHAT_LIST_POS_END: リストの最後に追加

- user_data: 任意のポインタ

戻り値:

- 新しい要素へのポインタ

C 言語での使用例:

    struct t_weelist_item *my_item =
        weechat_list_add (list, "my data", WEECHAT_LIST_POS_SORT, NULL);

スクリプト (Python) での使用例:

    # プロトタイプ
    def list_add(list: str, data: str, where: str, user_data: str) -> str: ...

    # 例
    item = weechat.list_add(list, "my data", weechat.WEECHAT_LIST_POS_SORT, "")

#### list_search

リストから要素を検索。

プロトタイプ:

    struct t_weelist_item *weechat_list_search (struct t_weelist *weelist,
                                                const char *data);

引数:

- weelist: リストへのポインタ

- data: リストから検索するデータ

戻り値:

- 見つかった要素へのポインタ、見つからなかった場合は NULL

C 言語での使用例:

    struct t_weelist_item *item = weechat_list_search (list, "my data");

スクリプト (Python) での使用例:

    # プロトタイプ
    def list_search(list: str, data: str) -> str: ...

    # 例
    item = weechat.list_search(list, "my data")

#### list_search_pos

WeeChat バージョン 0.3.4 以上で利用可。

リストから要素の位置を検索。

プロトタイプ:

    int weechat_list_search_pos (struct t_weelist *weelist,
                                 const char *data);

引数:

- weelist: リストへのポインタ

- data: リストから検索するデータ

戻り値:

- 見つかった要素の位置、見つからなかった場合は -1

C 言語での使用例:

    int pos_item = weechat_list_search_pos (list, "my data");

スクリプト (Python) での使用例:

    # プロトタイプ
    def list_search_pos(list: str, data: str) -> int: ...

    # 例
    pos_item = weechat.list_search_pos(list, "my data")

#### list_casesearch

大文字小文字を無視してリストから要素を検索。

プロトタイプ:

    struct t_weelist_item *weechat_list_casesearch (struct t_weelist *weelist,
                                                    const char *data);

引数:

- weelist: リストへのポインタ

- data: リストから検索するデータ

戻り値:

- 見つかった要素へのポインタ、見つからなかった場合は NULL

C 言語での使用例:

    struct t_weelist_item *item = weechat_list_casesearch (list, "my data");

スクリプト (Python) での使用例:

    # プロトタイプ
    def list_casesearch(list: str, data: str) -> str: ...

    # 例
    item = weechat.list_casesearch(list, "my data")

#### list_casesearch_pos

WeeChat バージョン 0.3.4 以上で利用可。

大文字小文字を無視してリストから要素の位置を検索。

プロトタイプ:

    int weechat_list_casesearch_pos (struct t_weelist *weelist,
                                     const char *data);

引数:

- weelist: リストへのポインタ

- data: リストから検索するデータ

戻り値:

- 見つかった要素の位置、見つからなかった場合は -1

C 言語での使用例:

    int pos_item = weechat_list_casesearch_pos (list, "my data");

スクリプト (Python) での使用例:

    # プロトタイプ
    def list_casesearch_pos(list: str, data: str) -> int: ...

    # 例
    pos_item = weechat.list_casesearch_pos(list, "my data")

#### list_get

リスト中の位置を指定して要素を返す。

プロトタイプ:

    struct t_weelist_item *weechat_list_get (struct t_weelist *weelist,
                                             int position);

引数:

- weelist: リストへのポインタ

- position: リスト中の位置 (1 番目の要素は 0)

戻り値:

- 見つかった要素へのポインタ、見つからなかった場合は NULL

C 言語での使用例:

    struct t_weelist_item *item = weechat_list_get (list, 0);  /* first item */

スクリプト (Python) での使用例:

    # プロトタイプ
    def list_get(list: str, position: int) -> str: ...

    # 例
    item = weechat.list_get(list, 0)

#### list_set

ある要素に新しい値をセット。

プロトタイプ:

    void weechat_list_set (struct t_weelist_item *item, const char *value);

引数:

- item: 要素へのポインタ

- value: 要素にセットする新しい値

C 言語での使用例:

    weechat_list_set (item, "new data");

スクリプト (Python) での使用例:

    # プロトタイプ
    def list_set(item: str, value: str) -> int: ...

    # 例
    weechat.list_set(item, "new data")

#### list_next

リストから 1 つ後の要素を返す。

プロトタイプ:

    struct t_weelist_item *weechat_list_next (struct t_weelist_item *item);

引数:

- item: 要素へのポインタ

戻り値:

- 1 つ後の要素へのポインタ、ポインタがリストの最後を指す場合は NULL

C 言語での使用例:

    struct t_weelist_item *next_item = weechat_list_next (item);

スクリプト (Python) での使用例:

    # プロトタイプ
    def list_next(item: str) -> str: ...

    # 例
    item = weechat.list_next(item)

#### list_prev

リストから 1 つ前の要素を返す。

プロトタイプ:

    struct t_weelist_item *weechat_list_prev (struct t_weelist_item *item);

引数:

- item: 要素へのポインタ

戻り値:

- 1 つ前の要素へのポインタ、ポインタがリストの最初を指す場合は NULL

C 言語での使用例:

    struct t_weelist_item *prev_item = weechat_list_prev (item);

スクリプト (Python) での使用例:

    # プロトタイプ
    def list_prev(item: str) -> str: ...

    # 例
    item = weechat.list_prev(item)

#### list_string

ある要素の文字列値を返す。

プロトタイプ:

    const char *weechat_list_string (struct t_weelist_item *item);

引数:

- item: 要素へのポインタ

戻り値:

- 要素の文字列値

C 言語での使用例:

    weechat_printf (NULL, "value of item: %s", weechat_list_string (item));

スクリプト (Python) での使用例:

    # プロトタイプ
    def list_string(item: str) -> str: ...

    # 例
    weechat.prnt("", "value of item: %s" % weechat.list_string(item))

#### list_user_data

WeeChat バージョン 2.6 以上で利用可

Return pointer to the user data of an item.

プロトタイプ:

    void *weechat_list_user_data (struct t_weelist_item *item);

引数:

- item: 要素へのポインタ

戻り値:

- pointer to the user data of item

C 言語での使用例:

    weechat_printf (NULL, "user data of item: %p", weechat_list_user_data (item));

注記 | スクリプト API ではこの関数を利用できません。

#### list_size

リストのサイズ (要素の個数) を返す。

プロトタイプ:

    char *weechat_list_size (struct t_weelist *weelist);

引数:

- weelist: 要素へのポインタ

戻り値:

- リストのサイズ (要素の個数)、リストが空の場合は 0

C 言語での使用例:

    weechat_printf (NULL, "size of list: %d", weechat_list_size (list));

スクリプト (Python) での使用例:

    # プロトタイプ
    def list_size(list: str) -> int: ...

    # 例
    weechat.prnt("", "size of list: %d" % weechat.list_size(list))

#### list_remove

ある要素をリストから削除。

プロトタイプ:

    void weechat_list_remove (struct t_weelist *weelist,
                              struct t_weelist_item *item);

引数:

- weelist: リストへのポインタ

- item: 要素へのポインタ

C 言語での使用例:

    weechat_list_remove (list, item);

スクリプト (Python) での使用例:

    # プロトタイプ
    def list_remove(list: str, item: str) -> int: ...

    # 例
    weechat.list_remove(list, item)

#### list_remove_all

あるリストの要素をすべて削除。

プロトタイプ:

    void weechat_list_remove_all (struct t_weelist *weelist);

引数:

- weelist: リストへのポインタ

C 言語での使用例:

    weechat_list_remove_all (list);

スクリプト (Python) での使用例:

    # プロトタイプ
    def list_remove_all(list: str) -> int: ...

    # 例
    weechat.list_remove_all(list)

#### list_free

リストを開放。

プロトタイプ:

    void weechat_list_free (struct t_weelist *weelist);

引数:

- weelist: リストへのポインタ

C 言語での使用例:

    weechat_list_free (list);

スクリプト (Python) での使用例:

    # プロトタイプ
    def list_free(list: str) -> int: ...

    # 例
    weechat.list_free(list)

### 3.9. 配列リスト

配列リスト関数。

配列リストとはサイズ可変でソート可能なポインタのリストです。

#### arraylist_new

WeeChat バージョン 1.8 以上で利用可

新しい配列リストを作成します。

プロトタイプ:

    struct t_arraylist *weechat_arraylist_new (int initial_size,
                                               int sorted,
                                               int allow_duplicates,
                                               int (*callback_cmp)(void *data,
                                                                   struct t_arraylist *arraylist,
                                                                   void *pointer1,
                                                                   void *pointer2),
                                               void *callback_cmp_data,
                                               void (*callback_free)(void *data,
                                                                     struct t_arraylist *arraylist,
                                                                     void *pointer),
                                               void *callback_free_data);

引数:

- initial_size: 配列リストの初期サイズ (要素数ではありません)

- sorted: 1 の場合には配列リストをソートし、0 の場合にはソートしません

- allow_duplicates: 1 の場合にはエントリの重複を許可し、0 の場合にはエントリが重複して追加されることを防ぎます

- callback_cmp: 2 つの要素を比較する際に使われるコールバック (任意)、引数と戻り値は以下:

  - void *data: ポインタ

  - struct t_arraylist *arraylist: 配列リストポインタ

  - void *pointer1: 1 番目の要素へのポインタ

  - void *pointer2: 2 番目の要素へのポインタ

  - 戻り値:

    - 1 番目の要素が 2 番目の要素よりも小さければ負数

    - 1 番目の要素が 2 番目の要素と同じならばゼロ

    - 1 番目の要素が 2 番目の要素よりも大きければ正数

- callback_cmp_data: WeeChat がコールバックを呼び出す際に、コールバックに渡すポインタ

- callback_free: 要素を解放する際に使われるコールバック (任意)、引数は以下:

  - void *data: ポインタ

  - struct t_arraylist *arraylist: 配列リストポインタ

  - void *pointer: 要素へのポインタ

- callback_free_data: WeeChat がコールバックを呼び出す際に、コールバックに渡すポインタ

戻り値:

- 新しい配列リストへのポインタ

C 言語での使用例:

    int
    cmp_cb (void *data, struct t_arraylist *arraylist,
            void *pointer1, void *pointer2)
    {
        if (...)
            return -1;
        else if (...)
            return 1;
        else
            return 0;
    }

    struct t_arraylist *list = weechat_arraylist_new (32, 1, 1,
                                                      &cmp_cb, NULL, NULL, NULL);

注記 | スクリプト API ではこの関数を利用できません。

#### arraylist_size

WeeChat バージョン 1.8 以上で利用可

配列リストのサイズ (要素ポインタの数) を返します。

プロトタイプ:

    int weechat_list_size (struct t_arraylist *arraylist);

引数:

- arraylist: 配列リストポインタ

戻り値:

- 配列リストのサイズ (要素の数)、0 は配列リストが空であることを意味します

C 言語での使用例:

    weechat_printf (NULL, "size of array list: %d", weechat_arraylist_size (arraylist));

注記 | スクリプト API ではこの関数を利用できません。

#### arraylist_get

WeeChat バージョン 1.8 以上で利用可

指定された位置の要素ポインタを返します。

プロトタイプ:

    void *weechat_arraylist_get (struct t_arraylist *arraylist, int index);

引数:

- arraylist: 配列リストポインタ

- index: リストのインデックス番号 (インデックス番号は 0 から始まります)

戻り値:

- ポインタが見つかった場合はそのポインタ、見つからなかった場合は NULL

C 言語での使用例:

    void *pointer = weechat_arraylist_get (arraylist, 0);  /* first item */

注記 | スクリプト API ではこの関数を利用できません。

#### arraylist_search

WeeChat バージョン 1.8 以上で利用可

配列リストから要素を検索します。

プロトタイプ:

    void *weechat_arraylist_search (struct t_arraylist *arraylist, void *pointer,
                                    int *index, int *index_insert);

引数:

- arraylist: 配列リストポインタ

- pointer: 配列リストから検索する要素へのポインタ

- index: 要素が見つかった場合はそのインデックス番号を示す整数へのポインタ、見つからなかった場合は -1 (任意)

- index_insert: arraylist に要素を挿入するために使われるインデックス番号を示す整数へのポインタ (これは arraylist のソート状態を保存する目的で使います) (任意)

戻り値:

- 要素が見つかったにはその要素へのポインタ、見つからなかった場合は NULL

C 言語での使用例:

    int index, index_insert;
    void *item = weechat_arraylist_search (arraylist, pointer, &index, &index_insert);

注記 | スクリプト API ではこの関数を利用できません。

#### arraylist_insert

WeeChat バージョン 1.8 以上で利用可

配列リストに要素を挿入します。

プロトタイプ:

    int weechat_arraylist_insert (struct t_arraylist *arraylist, int index, void *pointer);

引数:

- arraylist: 配列リストポインタ

- index: 配列リストにおける要素の挿入位置または末尾に挿入することを意味する -1 (この引数は配列リストがソート済みでない場合にのみ使われ、配列リストがソートされている場合には無視されます)

- pointer: 挿入する要素へのポインタ

戻り値:

- 成功した場合には挿入された要素のインデックス番号 (0 以上)、失敗した場合には -1。

C 言語での使用例:

    int index = weechat_arraylist_insert (arraylist, -1, pointer);  /* 未ソートの配列リストに対しては要素を末尾に挿入します */

注記 | スクリプト API ではこの関数を利用できません。

#### arraylist_add

WeeChat バージョン 1.8 以上で利用可

配列リストに要素を追加します。

プロトタイプ:

    int weechat_arraylist_add (struct t_arraylist *arraylist, void *pointer);

引数:

- arraylist: 配列リストポインタ

- pointer: 追加する要素へのポインタ

戻り値:

- 成功した場合には追加された要素のインデックス番号 (0 以上)、失敗した場合には -1。

C 言語での使用例:

    int index = weechat_arraylist_add (arraylist, pointer);

注記 | スクリプト API ではこの関数を利用できません。

#### arraylist_remove

WeeChat バージョン 1.8 以上で利用可

配列リストから要素を削除します。

プロトタイプ:

    int weechat_arraylist_remove (struct t_arraylist *arraylist, int index);

引数:

- arraylist: 配列リストポインタ

- index: 削除する要素のインデックス番号

戻り値:

- 成功した場合には削除された要素のインデックス番号、失敗した場合には -1。

C 言語での使用例:

    int index_removed = weechat_arraylist_remove (arraylist, index);

注記 | スクリプト API ではこの関数を利用できません。

#### arraylist_clear

WeeChat バージョン 1.8 以上で利用可

配列リストからすべての要素を削除します。

プロトタイプ:

    int weechat_arraylist_clear (struct t_arraylist *arraylist);

引数:

- arraylist: 配列リストポインタ

戻り値:

- 成功した場合には 1、失敗した場合には 0

C 言語での使用例:

    if (weechat_arraylist_clear (arraylist))
    {
        /* 成功 */
    }

注記 | スクリプト API ではこの関数を利用できません。

#### arraylist_free

WeeChat バージョン 1.8 以上で利用可

配列リストを解放します。

プロトタイプ:

    void weechat_arraylist_free (struct t_arraylist *arraylist);

引数:

- arraylist: 配列リストポインタ

C 言語での使用例:

    weechat_arraylist_free (arraylist);

注記 | スクリプト API ではこの関数を利用できません。

### 3.10. ハッシュテーブル

ハッシュテーブル関数。

#### hashtable_new

WeeChat バージョン 0.3.3 以上で利用可、バージョン 4.4.0 で更新。

新しいハッシュテーブルを作成。

プロトタイプ:

    struct t_hashtable *weechat_hashtable_new (int size,
                                               const char *type_keys,
                                               const char *type_values,
                                               unsigned long long (*callback_hash_key)(struct t_hashtable *hashtable,
                                                                                       const void *key),
                                               int (*callback_keycmp)(struct t_hashtable *hashtable,
                                                                      const void *key1,
                                                                      const void *key2));

引数:

- size: ハッシュキーを保存している内部配列のサイズ、値が大きければ多くのメモリを使う反面パフォーマンスがよくなります (これはハッシュテーブルの要素数の上限を決めるもの ではありません)

- type_keys: ハッシュテーブルのキーの種類:

  - WEECHAT_HASHTABLE_INTEGER

  - WEECHAT_HASHTABLE_STRING

  - WEECHAT_HASHTABLE_POINTER

  - WEECHAT_HASHTABLE_BUFFER

  - WEECHAT_HASHTABLE_TIME

  - WEECHAT_HASHTABLE_LONGLONG (WeeChat ≥ 4.4.0)

- type_values: ハッシュテーブルの値の種類:

  - WEECHAT_HASHTABLE_INTEGER

  - WEECHAT_HASHTABLE_STRING

  - WEECHAT_HASHTABLE_POINTER

  - WEECHAT_HASHTABLE_BUFFER

  - WEECHAT_HASHTABLE_TIME

  - WEECHAT_HASHTABLE_LONGLONG (WeeChat ≥ 4.4.0)

- callback_hash_key: キーを「ハッシュ化」する (キーを整数値にする) 際のコールバック関数、キーの種類が "buffer" 以外の場合、コールバックは NULL でも可 (デフォルトのハッシュ関数を使います)、引数と戻り値:

  - struct t_hashtable *hashtable: ハッシュテーブルへのポインタ

  - const void *key: キー

  - 戻り値: キーのハッシュ値

- callback_keycmp: 2 つのキーを比較する際のコールバック関数、キーの種類が "buffer" 以外の場合、コールバックは NULL でも可 (デフォルトの比較関数を使います)、引数と戻り値:

  - struct t_hashtable *hashtable: ハッシュテーブルへのポインタ

  - const void *key1: 1 番目のキー

  - const void *key2: 2 番目のキー

  - 戻り値:

    - key1 が key2 より小さい場合は負

    - key1 が key2 と同じ場合はゼロ

    - key1 が key2 より大きい場合は正

戻り値:

- 新しいハッシュテーブルへのポインタ、エラーが起きた場合は NULL

C 言語での使用例:

    struct t_hashtable *hashtable = weechat_hashtable_new (8,
                                                           WEECHAT_HASHTABLE_STRING,
                                                           WEECHAT_HASHTABLE_STRING,
                                                           NULL,
                                                           NULL);

注記 | スクリプト API ではこの関数を利用できません。

#### hashtable_set_with_size

WeeChat バージョン 0.3.3 以上で利用可、バージョン 0.4.2 で更新。

キーと値のサイズを使ってハッシュテーブルの要素を追加または更新。

プロトタイプ:

    struct t_hashtable_item *weechat_hashtable_set_with_size (struct t_hashtable *hashtable,
                                                              const void *key, int key_size,
                                                              const void *value, int value_size);

引数:

- hashtable: ハッシュテーブルへのポインタ

- key: キーへのポインタ

- key_size: キーのサイズ (バイト単位)、ハッシュテーブルのキーの種類が "buffer" の場合のみ使用

- value: 値へのポインタ

- value_size: 値のサイズ (バイト単位)、ハッシュテーブルの値の種類が "buffer" の場合のみ使用

戻り値:

- 作成または更新された要素へのポインタ、エラーが起きた場合は NULL

C 言語での使用例:

    weechat_hashtable_set_with_size (hashtable, "my_key", 0,
                                     my_buffer, sizeof (my_buffer_struct));

注記 | スクリプト API ではこの関数を利用できません。

#### hashtable_set

WeeChat バージョン 0.3.3 以上で利用可、バージョン 0.4.2 で更新。

ハッシュテーブルの要素を追加または更新。

プロトタイプ:

    struct t_hashtable_item *weechat_hashtable_set (struct t_hashtable *hashtable,
                                                    const void *key, const void *value);

引数:

- hashtable: ハッシュテーブルへのポインタ

- key: キーへのポインタ

- value: 値へのポインタ

戻り値:

- 作成または更新された要素へのポインタ、エラーが起きた場合は NULL

C 言語での使用例:

    weechat_hashtable_set (hashtable, "my_key", "my_value");

注記 | スクリプト API ではこの関数を利用できません。

#### hashtable_get

WeeChat バージョン 0.3.3 以上で利用可。

ハッシュテーブルからキーに紐付けられた値を取得。

プロトタイプ:

    void *weechat_hashtable_get (struct t_hashtable *hashtable, void *key);

引数:

- hashtable: ハッシュテーブルへのポインタ

- key: キーへのポインタ

戻り値:

- キーに対応する値、キーが見つからない場合は NULL

C 言語での使用例:

    void *value = weechat_hashtable_get (hashtable, "my_key");

注記 | スクリプト API ではこの関数を利用できません。

#### hashtable_has_key

WeeChat バージョン 0.3.4 以上で利用可。

ハッシュテーブル内にキーが有るか確認する。

プロトタイプ:

    int weechat_hashtable_has_key (struct t_hashtable *hashtable, void *key);

引数:

- hashtable: ハッシュテーブルへのポインタ

- key: キーへのポインタ

戻り値:

- ハッシュテーブル内にキーが有る場合は 1、無い場合は 0

C 言語での使用例:

    if (weechat_hashtable_has_key (hashtable, "my_key"))
    {
        /* key is in hashtable */
        /* ... */
    }

注記 | スクリプト API ではこの関数を利用できません。

#### hashtable_map

WeeChat バージョン 0.3.3 以上で利用可。

ハッシュテーブルのすべてのエントリに対して関数を呼び出す, by insertion order in the hashtable (from oldest to newest one).

プロトタイプ:

    void weechat_hashtable_map (struct t_hashtable *hashtable,
                                void (*callback_map)(void *data,
                                                     struct t_hashtable *hashtable,
                                                     const void *key,
                                                     const void *value),
                                void *callback_map_data);

引数:

- hashtable: ハッシュテーブルへのポインタ

- callback_map: ハッシュテーブルの各のエントリに対して呼び出すコールバック関数

- callback_map_data: callback_map コールバックを呼び出す際のコールバックの結果保存先へのポインタ

C 言語での使用例:

    void
    map_cb (void *data, struct t_hashtable *hashtable,
            const void *key, const void *value)
    {
        /* display key and value (they are both strings here) */
        weechat_printf (NULL, "key: '%s', value: '%s'",
                        (const char *)key,
                        (const char *)value);
    }
    /* ... */
    weechat_hashtable_map (hashtable, &map_cb, NULL);

注記 | スクリプト API ではこの関数を利用できません。

#### hashtable_map_string

WeeChat バージョン 0.3.7 以上で利用可。

Call a function on all hashtable entries, by insertion order in the hashtable (from oldest to newest one), sending keys and values as strings.

プロトタイプ:

    void weechat_hashtable_map_string (struct t_hashtable *hashtable,
                                       void (*callback_map)(void *data,
                                                            struct t_hashtable *hashtable,
                                                            const char *key,
                                                            const char *value),
                                       void *callback_map_data);

引数:

- hashtable: ハッシュテーブルへのポインタ

- callback_map: ハッシュテーブルの各のエントリに対して呼び出すコールバック関数

- callback_map_data: callback_map コールバックを呼び出した際のコールバックの結果保存先へのポインタ

注記 | コールバックに渡される文字列 key と value は一時的な文字列で、コールバックの呼び出しが終了したら削除されます。

C 言語での使用例:

    void
    map_cb (void *data, struct t_hashtable *hashtable,
            const char *key, const char *value)
    {
        /* display key and value */
        weechat_printf (NULL, "key: '%s', value: '%s'",
                        key, value);
    }
    /* ... */
    weechat_hashtable_map_string (hashtable, &map_cb, NULL);

注記 | スクリプト API ではこの関数を利用できません。

#### hashtable_dup

WeeChat バージョン 1.0 以上で利用可。

ハッシュテーブルを複製。

プロトタイプ:

    struct t_hashtable *weechat_hashtable_dup (struct t_hashtable *hashtable);

引数:

- hashtable: ハッシュテーブルへのポインタ

戻り値:

- 複製されたハッシュテーブ

C 言語での使用例:

    struct t_hashtable *new_hashtable = weechat_hashtable_dup (hashtable);

注記 | スクリプト API ではこの関数を利用できません。

#### hashtable_get_integer

WeeChat バージョン 0.3.3 以上で利用可。

ハッシュテーブルプロパティの整数値を返す。

プロトタイプ:

    int weechat_hashtable_get_integer (struct t_hashtable *hashtable,
                                       void *property);

引数:

- hashtable: ハッシュテーブルへのポインタ

- property: プロパティ名:

  - size: ハッシュテーブルの内部配列 "htable" のサイズ

  - items_count: ハッシュテーブルに含まれる要素の数

戻り値:

- プロパティの整数値

C 言語での使用例:

    int items_count = weechat_hashtable_get_integer (hashtable, "items_count");

注記 | スクリプト API ではこの関数を利用できません。

#### hashtable_get_string

WeeChat バージョン 0.3.4 以上で利用可。

ハッシュテーブルプロパティを文字列値で返す。

プロトタイプ:

    const char *weechat_hashtable_get_string (struct t_hashtable *hashtable,
                                              const char *property);

引数:

- hashtable: ハッシュテーブルへのポインタ

- property: プロパティ名:

  - type_keys: キーの型:

    - integer: 整数

    - string: 文字列

    - pointer: ポインタ

    - buffer: バッファ

    - time: 時間

    - longlong: long long integer

  - type_values: 値の型:

    - integer: 整数

    - string: 文字列

    - pointer: ポインタ

    - buffer: バッファ

    - time: 時間

    - longlong: long long integer

  - keys: キーのリストを含む文字列 (書式: "key1,key2,key3")

  - keys_sorted: ソートされたキーのリストを含む文字列 (書式: "key1,key2,key3")

  - values: 値のリストを含む文字列 (書式: "value1,value2,value3")

  - keys_values: リストのキーと値を含む文字列 (書式: "key1:value1,key2:value2,key3:value3")

  - keys_values_sorted: リストのキーと値を含む文字列 (キーでソート) (書式: "key1:value1,key2:value2,key3:value3")

戻り値:

- プロパティに対する結果の文字列

C 言語での使用例:

    weechat_printf (NULL, "keys are type: %s",
                    weechat_hashtable_get_string (hashtable, "type_keys"));
    weechat_printf (NULL, "list of keys: %s",
                    weechat_hashtable_get_string (hashtable, "keys"));

注記 | スクリプト API ではこの関数を利用できません。

#### hashtable_set_pointer

WeeChat バージョン 0.3.4 以上で利用可。

ハッシュテーブルのポインタ値を設定。

プロトタイプ:

    void weechat_hashtable_set_pointer (struct t_hashtable *hashtable,
                                        const char *property, void *pointer);

引数:

- hashtable: ハッシュテーブルへのポインタ

- property: プロパティ名:

  - callback_free_key: ハッシュテーブルからキーを開放する際のコールバック関数 (WeeChat バージョン 0.4.2 以上で利用可)

  - callback_free_value: ハッシュテーブルから値を開放する際のコールバック関数

- pointer: プロパティの新しいポインタ値

C 言語での使用例:

    void
    my_free_value_cb (struct t_hashtable *hashtable, const void *key, void *value)
    {
        /* ... */
    }

    void
    my_free_key_cb (struct t_hashtable *hashtable, void *key)
    {
        /* ... */
    }

    weechat_hashtable_set_pointer (hashtable, "callback_free_value", &my_free_value_cb);
    weechat_hashtable_set_pointer (hashtable, "callback_free_key", &my_free_key_cb);

注記 | スクリプト API ではこの関数を利用できません。

#### hashtable_add_to_infolist

WeeChat バージョン 0.3.3 以上で利用可。

ハッシュテーブルの要素をインフォリスト要素に追加, by insertion order in the hashtable (from oldest to newest one).

プロトタイプ:

    int weechat_hashtable_add_to_infolist (struct t_hashtable *hashtable,
                                           struct t_infolist_item *infolist_item,
                                           const char *prefix);

引数:

- hashtable: ハッシュテーブルへのポインタ

- infolist_item: インフォリスト要素へのポインタ

- prefix: インフォリストで名前のプレフィックスとして使う文字列

戻り値:

- 成功した場合は 1、エラーが起きた場合は 0

C 言語での使用例:

    weechat_hashtable_add_to_infolist (hashtable, infolist_item, "testhash");

    /* ハッシュテーブルが以下の内容を保つ場合:
         "key1" => "value 1"
         "key2" => "value 2"
       以下の変数がインフォリスト要素に追加されます:
         "testhash_name_00000"  = "key1"
         "testhash_value_00000" = "value 1"
         "testhash_name_00001"  = "key2"
         "testhash_value_00001" = "value 2"
    */

注記 | スクリプト API ではこの関数を利用できません。

#### hashtable_remove

WeeChat バージョン 0.3.3 以上で利用可。

ハッシュテーブルから要素を削除。

プロトタイプ:

    void weechat_hashtable_remove (struct t_hashtable *hashtable, const void *key);

引数:

- hashtable: ハッシュテーブルへのポインタ

- key: キーへのポインタ

C 言語での使用例:

    weechat_hashtable_remove (hashtable, "my_key");

注記 | スクリプト API ではこの関数を利用できません。

#### hashtable_remove_all

WeeChat バージョン 0.3.3 以上で利用可。

ハッシュテーブルからすべての要素を削除。

プロトタイプ:

    void weechat_hashtable_remove_all (struct t_hashtable *hashtable);

引数:

- hashtable: ハッシュテーブルへのポインタ

C 言語での使用例:

    weechat_hashtable_remove_all (hashtable);

注記 | スクリプト API ではこの関数を利用できません。

#### hashtable_free

WeeChat バージョン 0.3.3 以上で利用可。

ハッシュテーブルを開放。

プロトタイプ:

    void weechat_hashtable_free (struct t_hashtable *hashtable);

引数:

- hashtable: ハッシュテーブルへのポインタ

C 言語での使用例:

    weechat_hashtable_free (hashtable);

注記 | スクリプト API ではこの関数を利用できません。

### 3.11. 設定ファイル

設定ファイルに関する関数。

#### config_new

WeeChat バージョン 1.5, 4.0.0 で更新。

新しい設定ファイルを作成。

プロトタイプ:

    struct t_config_file *weechat_config_new (const char *name,
                                              int (*callback_reload)(const void *pointer,
                                                                     void *data,
                                                                     struct t_config_file *config_file),
                                              const void *callback_reload_pointer,
                                              void *callback_reload_data);

引数:

- name: 設定ファイルの名前 (パスと拡張子は不要); a priority is allowed before the name, with format `nnn|name` where `nnn` is non-negative integer with priority; default priority is 1000; files are sorted by priority from higher to lower when running command `/reload` (see priority of configuration files below)

- callback_reload: `/reload` で設定ファイルをリロードする際に呼び出すコールバック関数 (任意、NULL でも可、下の説明を参照)、引数と戻り値:

  - const void *pointer: ポインタ

  - void *data: ポインタ

  - struct t_config_file *config_file: 設定ファイルへのポインタ

  - 戻り値:

    - WEECHAT_CONFIG_READ_OK

    - WEECHAT_CONFIG_READ_MEMORY_ERROR

    - WEECHAT_CONFIG_READ_FILE_NOT_FOUND

- callback_reload_pointer: WeeChat が callback_reload コールバックを呼び出す際にコールバックに渡すポインタ

- callback_reload_data: WeeChat が callback_reload コールバックを呼び出す際にコールバックに渡すポインタ; このポインタが NULL でない場合、このポインタは malloc (または類似の関数) によって割り当てられたものでなければいけません。さらに、このポインタはここで作成した設定ファイルが開放された時点で自動的に開放されます

リロードコールバック:

- リロードコールバックは必ず config_reload を呼び出してください。config_reload 関数は設定ファイルを削除してはいけません。

- config_reload 関数の前処理や後処理が必要な場合に限り、これらを行うリロードコールバックを指定します。
  リロードコールバックを指定しなかった場合、WeeChat は内部リロード関数を呼び出し、常に設定ファイルがリロードされます。

戻り値:

- 新しい設定ファイルへのポインタ、エラーが起きた場合は NULL

注記 | この関数はディスク上にファイルを作りません。ファイルを作るには config_write 関数を使ってください。この関数を呼び出す必要があるのは (config_new_section を使って) セクションもしくは (config_new_option を使って) オプションを追加した後だけです。

Priority of default configuration files:

Rank | File | Priority
--- | --- | ---
1 | sec.conf | 120000
2 | weechat.conf | 110000
3 | plugins.conf | 100000
4 | charset.conf | 16000
5 | logger.conf | 15000
6 | exec.conf | 14000
7 | trigger.conf | 13000
8 | spell.conf | 12000
9 | alias.conf | 11000
10 | buflist.conf | 10000
11 | fifo.conf | 9000
12 | typing.conf | 8000
13 | xfer.conf | 7000
14 | irc.conf | 6000
15 | relay.conf | 5000
16 | guile.conf | 4070
17 | lua.conf | 4050
18 | perl.conf | 4040
19 | php.conf | 4030
20 | python.conf | 4020
21 | ruby.conf | 4010
22 | tcl.conf | 4000
23 | script.conf | 3000
24 | fset.conf | 2000

C 言語での使用例:

    int
    my_config_reload_cb (const void *pointer, void *data,
                         struct t_config_file *config_file)
    {
        /* ... */

        return WEECHAT_RC_OK;
    }

    struct t_config_file *config_file = weechat_config_new ("test",
                                                            &my_config_reload_cb,
                                                            NULL, NULL);

スクリプト (Python) での使用例:

    # プロトタイプ
    def config_new(name: str, callback_reload: str, callback_reload_data: str) -> str: ...

    # 例
    def my_config_reload_cb(data: str, config_file: str) -> int:
        # ...
        return weechat.WEECHAT_RC_OK

    config_file = weechat.config_new("test", "my_config_reload_cb", "")

#### config_set_version

WeeChat ≥ 4.0.0.

Set configuration file version and a callback to update config sections/options on-the-fly when the config is read.

プロトタイプ:

    int config_file_set_version (struct t_config_file *config_file,
                                 int version,
                                 struct t_hashtable *(*callback_update)(const void *pointer,
                                                                        void *data,
                                                                        struct t_config_file *config_file,
                                                                        int version_read,
                                                                        struct t_hashtable *data_read),
                                 const void *callback_update_pointer,
                                 void *callback_update_data);

引数:

- config_file: configuration file pointer

- version: version, must be ≥ 2

- callback_update: function called when configuration file is read, for each section and each option, if the version read is less than the expected version, (optional, can be NULL, see below), arguments and return value:

  - const void *pointer: pointer

  - void *data: pointer

  - struct t_config_file *config_file: configuration file pointer

  - int version_read: version read in configuration file (1 by default)

  - struct t_hashtable *data_read: hashtable with data read from configuration file (see below)

  - return value:

    - either "data_read" pointer (hashtable completed), or pointer to a new hashtable (created by callback, with keys and values of type "string")

- callback_update_pointer: pointer given to callback when it is called by WeeChat

- callback_update_data: pointer given to callback when it is called by WeeChat; if not NULL, it must have been allocated with malloc (or similar function) and it is automatically freed when the configuration file is freed

Update callback:

- The callback receives a hashtable with data read from configuration file:

Key | Availability | Value
--- | --- | ---
`config` | Always set | Name of configuration file, without extension (eg: `weechat`)
`section` | Always set | Name of section being read
`option` | For option only | Name of the option
`value` | For option only | Value of the option (if not NULL)
`value_null` | For option only | Option as NULL value (value is always `1`)

- The callback can update "section" for a line with a section and "option", "value" and "value_null" for a line with an option.

- If "option" is set to empty string by the callback, the line read in configuration file is ignored.

- Field "value_null" is set to force a NULL value for the option.

戻り値:

- 1 if OK, 0 if error

C 言語での使用例:

    struct t_hashtable *
    my_config_update_cb (const void *pointer, void *data,
                         struct t_config_file *config_file,
                         int version_read,
                         struct t_hashtable *data_read)
    {
        const char *ptr_section, *ptr_option;

        /* return now if version is already up-to-date */
        if (version_read >= 2)
            return NULL;

        ptr_section = hashtable_get (data_read, "section");
        ptr_option = hashtable_get (data_read, "option");

        /* rename section "abc" to "def" */
        if (ptr_section && !ptr_option && (strcmp (ptr_section, "abc") == 0))
        {
            hashtable_set (data_read, "section", "def");
            return data_read;
        }

        /* limit other changes to section "test" */
        if (!ptr_section || !ptr_option || (strcmp (ptr_section, "test") != 0))
            return NULL;

        /* rename option "test1" to "test2" */
        if (strcmp (ptr_option, "test1") == 0)
        {
            hashtable_set (data_read, "option", "test2");
            return data_read;
        }

        /* set value to "xxx" for option "test" */
        if (strcmp (ptr_option, "test") == 0)
        {
            hashtable_set (data_read, "value", "xxx");
            return data_read;
        }

        /* set value to NULL for option "test_null" */
        if (strcmp (ptr_option, "test_null") == 0)
        {
            hashtable_set (data_read, "value_null", "1");
            return data_read;
        }

        /* no changes */
        return NULL;
    }

    struct t_config_file *config_file = weechat_config_new ("test", NULL, NULL, NULL);
    weechat_config_set_version (config_file, 2, &my_config_update_cb, NULL, NULL);
    weechat_config_read (config_file);

スクリプト (Python) での使用例:

    # プロトタイプ
    def config_set_version(config_file: str, version: int, callback_update: str, callback_update_data: str) -> int: ...

    # 例
    def my_config_update_cb(data: str, config_file: str, version_read: int, data_read: Dict[str, str]) -> Dict[str, str]:
        # return now if version is already up-to-date
        if version_read >= 2:
            return {}

        section = data_read.get("section")
        option = data_read.get("option")

        # rename section "abc" to "def"
        if section and not option and section == "abc":
            data_read["section"] = "def"
            return data_read

        # limit other changes to section "test"
        if not section or not option or section != "test":
            return {}

        # rename option "test1" to "test2"
        if option == "test1":
            data_read["option"] = "test2"
            return data_read

        # set value to "xxx" for option "test"
        if option == "test":
            data_read["value"] = "xxx"
            return data_read

        # set value to NULL for option "test_null"
        if option == "test_null":
            data_read["value_null"] = "1"
            return data_read

        # no changes
        return {}

    config_file = weechat.config_new("test", "", "")
    weechat.config_set_version(config_file, 2, "my_config_update_cb", "")
    weechat.config_read(config_file)

#### config_new_section

WeeChat バージョン 1.5 で更新。

設定ファイルに新しいセクションを作成する。

プロトタイプ:

    struct t_config_section *weechat_config_new_section (
        struct t_config_file *config_file,
        const char *name,
        int user_can_add_options,
        int user_can_delete_options,
        int (*callback_read)(const void *pointer,
                             void *data,
                             struct t_config_file *config_file,
                             struct t_config_section *section,
                             const char *option_name,
                             const char *value),
        const void *callback_read_pointer,
        void *callback_read_data,
        int (*callback_write)(const void *pointer,
                              void *data,
                              struct t_config_file *config_file,
                              const char *section_name),
        const void *callback_write_pointer,
        void *callback_write_data,
        int (*callback_write_default)(const void *pointer,
                                      void *data,
                                      struct t_config_file *config_file,
                                      const char *section_name),
        const void *callback_write_default_pointer,
        void *callback_write_default_data,
        int (*callback_create_option)(const void *pointer,
                                      void *data,
                                      struct t_config_file *config_file,
                                      struct t_config_section *section,
                                      const char *option_name,
                                      const char *value),
        const void *callback_create_option_pointer,
        void *callback_create_option_data,
        int (*callback_delete_option)(const void *pointer,
                                      void *data,
                                      struct t_config_file *config_file,
                                      struct t_config_section *section,
                                      struct t_config_option *option),
        const void *callback_delete_option_pointer,
        void *callback_delete_option_data);

引数:

- config_file: 設定ファイルへのポインタ

- name: セクションの名前

- user_can_add_options: ユーザがこのセクションに新しいオプションを作成することを許可する場合は 1、禁止する場合は 0

- user_can_delete_options: ユーザがこのセクションからオプションを削除することを許可する場合は 1、禁止する場合は 0

- callback_read: このセクションに含まれるオプションがディスクから読まれた際に呼び出すコールバック関数 (特別な関数を使ってセクションを読み出す必要がある場合を除いて、殆どの場合は NULL を指定する)、引数と戻り値:

  - const void *pointer: ポインタ

  - void *data: ポインタ

  - struct t_config_file *config_file: 設定ファイルへのポインタ

  - struct t_config_section *section: セクションへのポインタ

  - const char *option_name: オプションの名前

  - const char *value: 値

  - 戻り値:

    - 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

- callback_read_pointer: WeeChat が callback_read コールバックを呼び出す際にコールバックに渡すポインタ

- callback_read_data: WeeChat が callback_read コールバックを呼び出す際にコールバックに渡すポインタ; このポインタが NULL でない場合、このポインタは malloc (または類似の関数) によって割り当てられたものでなければいけません。さらに、このポインタはここで作成したセクションが開放された時点で自動的に開放されます

- callback_write: セクションをファイルに書き込む際に呼び出すコールバック関数 (特別な関数を使ってセクションを書き込む必要がある場合を除いて、殆どの場合は NULL を指定する)、引数と戻り値:

  - const void *pointer: ポインタ

  - void *data: ポインタ

  - struct t_config_file *config_file: 設定ファイルへのポインタ

  - const char *section_name: セクションの名前

  - 戻り値:

    - WEECHAT_CONFIG_WRITE_OK

    - WEECHAT_CONFIG_WRITE_ERROR

    - WEECHAT_CONFIG_WRITE_MEMORY_ERROR

- callback_write_pointer: WeeChat が callback_write コールバックを呼び出す際にコールバックに渡すポインタ

- callback_write_data: WeeChat が callback_write コールバックを呼び出す際にコールバックに渡すポインタ; このポインタが NULL でない場合、このポインタは malloc (または類似の関数) によって割り当てられたものでなければいけません。さらに、このポインタはここで作成したセクションが開放された時点で自動的に開放されます

- callback_write_default: セクションのデフォルト値が必ずファイルに書き込まれる際に呼び出すコールバック関数、引数と戻り値:

  - const void *pointer: ポインタ

  - void *data: ポインタ

  - struct t_config_file *config_file: 設定ファイルへのポインタ

  - const char *section_name: セクションの名前

  - 戻り値:

    - WEECHAT_CONFIG_WRITE_OK

    - WEECHAT_CONFIG_WRITE_ERROR

    - WEECHAT_CONFIG_WRITE_MEMORY_ERROR

- callback_write_default_pointer: WeeChat が callback_write_default コールバックを呼び出す際にコールバックに渡すポインタ

- callback_write_default_data: WeeChat が callback_write_default コールバックを呼び出す際にコールバックに渡すポインタ; このポインタが NULL でない場合、このポインタは malloc (または類似の関数) によって割り当てられたものでなければいけません。さらに、このポインタはここで作成したセクションが開放された時点で自動的に開放されます

- callback_create_option: セクションに新しいオプションを作成する際に呼び出すコールバック関数 (セクションに新しいオプションを作成することを禁止する場合は NULL)、引数と戻り値:

  - const void *pointer: ポインタ

  - void *data: ポインタ

  - struct t_config_file *config_file: 設定ファイルへのポインタ

  - struct t_config_section *section: セクションへのポインタ

  - const char *option_name: オプションの名前

  - const char *value: 値

  - 戻り値:

    - 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

- callback_create_option_pointer: WeeChat が callback_create_option コールバックを呼び出す際にコールバックに渡すポインタ

- callback_create_option_data: WeeChat が callback_create_option コールバックを呼び出す際にコールバックに渡すポインタ; このポインタが NULL でない場合、このポインタは malloc (または類似の関数) によって割り当てられたものでなければいけません。さらに、このポインタはここで作成したセクションが開放された時点で自動的に開放されます

- callback_delete_option: セクションからオプションを削除する際に呼び出すコールバック関数 (セクションからオプションを削除することを禁止する場合は NULL)、引数と戻り値:

  - const void *pointer: ポインタ

  - void *data: ポインタ

  - struct t_config_file *config_file: 設定ファイルへのポインタ

  - struct t_config_section *section: セクションへのポインタ

  - struct t_config_option *option: オプションへのポインタ

  - 戻り値:

    - WEECHAT_CONFIG_OPTION_UNSET_OK_NO_RESET

    - WEECHAT_CONFIG_OPTION_UNSET_OK_RESET

    - WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED

    - WEECHAT_CONFIG_OPTION_UNSET_ERROR

- callback_delete_option_pointer: WeeChat が callback_delete_option コールバックを呼び出す際にコールバックに渡すポインタ

- callback_delete_option_data: WeeChat が callback_delete_option コールバックを呼び出す際にコールバックに渡すポインタ; このポインタが NULL でない場合、このポインタは malloc (または類似の関数) によって割り当てられたものでなければいけません。さらに、ポインタはここで作成したセクションが開放された時点で自動的に開放されます

戻り値:

- 設定ファイルの新しいセクションへのポインタ、エラーが起きた場合は NULL

C 言語での使用例:

    int
    my_section_read_cb (const void *pointer, void *data,
                        struct t_config_file *config_file,
                        struct t_config_section *section,
                        const char *option_name,
                        const char *value)
    {
        /* ... */

        return WEECHAT_CONFIG_OPTION_SET_OK_CHANGED;
        /* return WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE; */
        /* return WEECHAT_CONFIG_OPTION_SET_ERROR; */
        /* return WEECHAT_CONFIG_OPTION_SET_OPTION_NOT_FOUND; */
    }

    int
    my_section_write_cb (const void *pointer, void *data,
                         struct t_config_file *config_file,
                         const char *section_name)
    {
        /* ... */

        return WEECHAT_CONFIG_WRITE_OK;
        /* return WEECHAT_CONFIG_WRITE_ERROR; */
        /* return WEECHAT_CONFIG_WRITE_MEMORY_ERROR; */
    }

    int
    my_section_write_default_cb (const void *pointer, void *data,
                                 struct t_config_file *config_file,
                                 const char *section_name)
    {
        /* ... */

        return WEECHAT_CONFIG_WRITE_OK;
        /* return WEECHAT_CONFIG_WRITE_ERROR; */
        /* return WEECHAT_CONFIG_WRITE_MEMORY_ERROR; */
    }

    int
    my_section_create_option_cb (const void *pointer, void *data,
                                 struct t_config_file *config_file,
                                 struct t_config_section *section,
                                 const char *option_name,
                                 const char *value)
    {
        /* ... */

        return WEECHAT_CONFIG_OPTION_SET_OK_CHANGED;
        /* return WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE; */
        /* return WEECHAT_CONFIG_OPTION_SET_ERROR; */
        /* return WEECHAT_CONFIG_OPTION_SET_OPTION_NOT_FOUND; */
    }

    int
    my_section_delete_option_cb (const void *pointer, void *data,
                                 struct t_config_file *config_file,
                                 struct t_config_section *section,
                                 struct t_config_option *option)
    {
        /* ... */

        return WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED;
        /* return WEECHAT_CONFIG_OPTION_UNSET_OK_NO_RESET; */
        /* return WEECHAT_CONFIG_OPTION_UNSET_OK_RESET; */
        /* return WEECHAT_CONFIG_OPTION_UNSET_ERROR; */
    }

    /* standard section, user cannot add/delete options */
    struct t_config_section *new_section1 =
        weechat_config_new_section (config_file, "section1", 0, 0,
                                    NULL, NULL, NULL,
                                    NULL, NULL, NULL,
                                    NULL, NULL, NULL,
                                    NULL, NULL, NULL,
                                    NULL, NULL, NULL);

    /* special section, user can add/delete options, and options need
       callback to be read/written */
    struct t_config_section *new_section2 =
        weechat_config_new_section (config_file, "section2", 1, 1,
                                    &my_section_read_cb, NULL, NULL,
                                    &my_section_write_cb, NULL, NULL,
                                    &my_section_write_default_cb, NULL, NULL,
                                    &my_section_create_option_cb, NULL, NULL,
                                    &my_section_delete_option_cb, NULL, NULL);

スクリプト (Python) での使用例:

    # プロトタイプ
    def config_new_section(config_file: str, name: str,
                           user_can_add_options: int, user_can_delete_options: int,
                           callback_read: str, callback_read_data: str,
                           callback_write: str, callback_write_data: str,
                           callback_write_default: str, callback_write_default_data: str,
                           callback_create_option: str, callback_create_option_data: str,
                           callback_delete_option: str, callback_delete_option_data: str) -> str: ...

    # 例
    def my_section_read_cb(data: str, config_file: str, section: str, option_name: str, value: Union[str, None]) -> int:
        # ...
        return weechat.WEECHAT_CONFIG_OPTION_SET_OK_CHANGED
        # return weechat.WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE
        # return weechat.WEECHAT_CONFIG_OPTION_SET_ERROR
        # return weechat.WEECHAT_CONFIG_OPTION_SET_OPTION_NOT_FOUND

    def my_section_write_cb(data: str, config_file: str, section_name: str) -> int:
        # ...
        return weechat.WEECHAT_CONFIG_WRITE_OK
        # return weechat.WEECHAT_CONFIG_WRITE_ERROR
        # return weechat.WEECHAT_CONFIG_WRITE_MEMORY_ERROR

    def my_section_write_default_cb(data: str, config_file: str, section_name: str) -> int:
        # ...
        return weechat.WEECHAT_CONFIG_WRITE_OK
        # return weechat.WEECHAT_CONFIG_WRITE_ERROR
        # return weechat.WEECHAT_CONFIG_WRITE_MEMORY_ERROR

    def my_section_create_option_cb(data: str, config_file: str, section: str, option_name: str, value: Union[str, None]) -> int:
        # ...
        return weechat.WEECHAT_CONFIG_OPTION_SET_OK_CHANGED
        # return weechat.WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE
        # return weechat.WEECHAT_CONFIG_OPTION_SET_ERROR
        # return weechat.WEECHAT_CONFIG_OPTION_SET_OPTION_NOT_FOUND

    def my_section_delete_option_cb(data: str, config_file: str, section: str, option: str) -> int:
        # ...
        return weechat.WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED
        # return weechat.WEECHAT_CONFIG_OPTION_UNSET_OK_NO_RESET
        # return weechat.WEECHAT_CONFIG_OPTION_UNSET_OK_RESET
        # return weechat.WEECHAT_CONFIG_OPTION_UNSET_ERROR

    section = weechat.config_new_section(config_file, "section1", 1, 1,
        "my_section_read_cb", "",
        "my_section_write_cb", "",
        "my_section_write_default_cb", "",
        "my_section_create_option_cb", "",
        "my_section_delete_option_cb", "")

#### config_search_section

設定ファイルからセクションを検索。

プロトタイプ:

    struct t_config_section *weechat_config_search_section (
        struct t_config_file *config_file,
        const char *section_name);

引数:

- config_file: 設定ファイルへのポインタ

- section_name: 検索するセクションの名前

戻り値:

- セクションが見つかった場合はセクションへのポインタ、見つからなかった場合は NULL

C 言語での使用例:

    struct t_config_section *section = weechat_config_search_section (config_file,
                                                                      "section");

スクリプト (Python) での使用例:

    # プロトタイプ
    def config_search_section(config_file: str, section_name: str) -> str: ...

    # 例
    section = weechat.config_search_section(config_file, "section")

#### config_new_option

Updated in 1.5, 4.1.0.

設定ファイルのあるセクションに新しいオプションを作成。

プロトタイプ:

    struct t_config_option *weechat_config_new_option (
        struct t_config_file *config_file,
        struct t_config_section *section,
        const char *name,
        const char *type,
        const char *description,
        const char *string_values,
        int min,
        int max,
        const char *default_value,
        const char *value,
        int null_value_allowed,
        int (*callback_check_value)(const void *pointer,
                                    void *data,
                                    struct t_config_option *option,
                                    const char *value),
        const void *callback_check_value_pointer,
        void *callback_check_value_data,
        void (*callback_change)(const void *pointer,
                                void *data,
                                struct t_config_option *option),
        const void *callback_change_pointer,
        void *callback_change_data,
        void (*callback_delete)(const void *pointer,
                                void *data,
                                struct t_config_option *option),
        const void *callback_delete_pointer,
        void *callback_delete_data);

引数:

- config_file: 設定ファイルへのポインタ

- section: セクションへのポインタ

- name: オプションの名前; WeeChat バージョン 1.4 以上の場合、名前には親オプションの名前を含めることも可能です (このオプションが "null" の場合、親オプションの値が `/set` コマンドの出力に表示されます)。以下の構文を使ってください: "name << file.section.option"

- type: オプションの型:

  - boolean: ブール値 (on/off)

  - integer: 整数値

  - string: 文字列

  - color: 色

  - enum: list of string values (stored as integer internally)

- description: オプションの説明

- string_values: 文字列で値を受ける (`|` で区切る) (optional, required for type enum)

- min: 最小値 (integer 型で有効)

- max: 最大値 (integer 型で有効)

- default_value: オプションのデフォルト値 (オプションをリセットした際に使われる)

- value: オプションの値

- null_value_allowed: オプションに null (未定義値) を設定することを許可する場合に 1、禁止する場合は 0

- callback_check_value: オプションの新しい値をチェックする際に呼び出すコールバック関数 (任意)、引数と戻り値:

  - const void *pointer: ポインタ

  - void *data: ポインタ

  - struct t_config_option *option: オプションへのポインタ

  - const char *value: オプションの新しい値

  - 戻り値:

    - 値が有効の場合は 1

    - 値が無効の場合は 0

- callback_check_value_pointer: WeeChat が callback_check_value コールバックを呼び出す際にコールバックに渡すポインタ

- callback_check_value_data: WeeChat が callback_check_value コールバックを呼び出す際にコールバックに渡すポインタ; このポインタが NULL でない場合、このポインタは malloc (または類似の関数) によって割り当てられたものでなければいけません。さらに、このポインタはここで作成したオプションが開放された時点で自動的に開放されます

- callback_change: オプションの値を変更した際に呼び出すコールバック関数 (任意)、引数:

  - const void *pointer: ポインタ

  - void *data: ポインタ

  - struct t_config_option *option: オプションへのポインタ

- callback_change_pointer: WeeChat が callback_change コールバックを呼び出す際にコールバックに渡すポインタ

- callback_change_data: WeeChat が callback_change コールバックを呼び出す際にコールバックに渡すポインタ; このポインタが NULL でない場合、このポインタは malloc (または類似の関数) によって割り当てられたものでなければいけません。さらに、このポインタはここで作成したオプションが開放された時点で自動的に開放されます

- callback_delete: オプションを削除する前に際に呼び出すコールバック関数 (任意)、引数:

  - const void *pointer: ポインタ

  - void *data: ポインタ

  - struct t_config_option *option: オプションへのポインタ

- callback_delete_pointer: WeeChat が callback_delete コールバックを呼び出す際にコールバックに渡すポインタ

- callback_delete_data: WeeChat が callback_delete コールバックを呼び出す際にコールバックに渡すポインタ; このポインタが NULL でない場合、このポインタは malloc (または類似の関数) によって割り当てられたものでなければいけません。さらに、このポインタはここで作成したオプションが開放された時点で自動的に開放されます

戻り値:

- セクションの新しいオプションへのポインタ、エラーが起きた場合は NULL

C 言語での使用例:

    /* boolean */
    struct t_config_option *option_bool =
        weechat_config_new_option (config_file, section, "option_bool", "boolean",
                                   "My option, type boolean",
                                   NULL,
                                   0, 0,
                                   "on",
                                   "on",
                                   0,
                                   NULL, NULL, NULL,
                                   NULL, NULL, NULL,
                                   NULL, NULL, NULL);

    /* integer */
    struct t_config_option *option_int =
        weechat_config_new_option (config_file, section, "option_int", "integer",
                                   "My option, type integer",
                                   NULL,
                                   0, 100,
                                   "15",
                                   "15",
                                   0,
                                   NULL, NULL, NULL,
                                   NULL, NULL, NULL,
                                   NULL, NULL, NULL);

    /* string */
    struct t_config_option *option_str =
        weechat_config_new_option (config_file, section, "option_str", "string",
                                   "My option, type string",
                                   NULL,
                                   0, 0,
                                   "test",
                                   "test",
                                   1,
                                   NULL, NULL, NULL,
                                   NULL, NULL, NULL,
                                   NULL, NULL, NULL);

    /* color */
    struct t_config_option *option_col =
        weechat_config_new_option (config_file, section, "option_col", "color",
                                   "My option, type color",
                                   NULL,
                                   0, 0,
                                   "lightblue",
                                   "lightblue",
                                   0,
                                   NULL, NULL, NULL,
                                   NULL, NULL, NULL,
                                   NULL, NULL, NULL);

    /* enum */
    struct t_config_option *option_enum =
        weechat_config_new_option (config_file, section, "option_enum", "enum",
                                   "My option, type enum",
                                   "top|bottom|left|right",
                                   0, 0,
                                   "bottom",
                                   "bottom",
                                   0,
                                   NULL, NULL, NULL,
                                   NULL, NULL, NULL,
                                   NULL, NULL, NULL);

スクリプト (Python) での使用例:

    # プロトタイプ
    def config_new_option(config_file: str, section: str, name: str, type: str, description: str,
                          string_values: str, min: int, max: int,
                          default_value: Union[str, None], value: Union[str, None], null_value_allowed: int,
                          callback_check_value: str, callback_check_value_data: str,
                          callback_change: str, callback_change_data: str,
                          callback_delete: str, callback_delete_data: str) -> str: ...

    # 例
    def option_str_check_value_cb(data: str, option: str, value: str) -> int:
        # ...
        return 1
        # return 0

    def option_str_change_cb(data: str, option: str) -> None:
        # ...

    def option_str_delete_cb(data: str, option: str) -> None:
        # ...

    option_bool = weechat.config_new_option(config_file, section, "option_bool", "boolean",
        "My option, type boolean",
        "", 0, 0, "on", "on", 0,
        "", "",
        "", "",
        "", "")

    option_int = weechat.config_new_option(config_file, section, "option_int", "integer",
        "My option, type integer",
        "", 0, 100, "15", "15", 0,
        "", "",
        "", "",
        "", "")

    option_str = weechat.config_new_option(config_file, section, "option_str", "string",
        "My option, type string",
        "", 0, 0, "test", "test", 1,
        "option_str_check_value_cb", "",
        "option_str_change_cb", "",
        "option_str_delete_cb", "")

    option_col = weechat.config_new_option(config_file, section, "option_col", "color",
        "My option, type color",
        "", 0, 0, "lightblue", "lightblue", 0,
        "", "",
        "", "",
        "", "")

    option_enum = weechat.config_new_option(config_file, section, "option_enum", "enum",
        "My option, type enum",
        "top|bottom|left|right",
        0, 0, "bottom", "bottom", 0,
        "", "",
        "", "",
        "", "")

注記 | Ruby では、3 組のコールバックとデータ (6 つの文字列変数) を渡す際に必ず 6 つの文字列変数の配列を 1 つ渡してください (これは Ruby が関数に 15 個以上の引数を渡せないことが原因です)、より詳しい内容は WeeChat スクリプト作成ガイド ↗を参照してください (WeeChat バージョン 0.4.1 で修正済み)。

#### config_search_option

設定ファイルのセクションからオプションを検索。

プロトタイプ:

    struct t_config_option *weechat_config_search_option (
        struct t_config_file *config_file,
        struct t_config_section *section,
        const char *option_name);

引数:

- config_file: 設定ファイルへのポインタ

- section: セクションへのポインタ

- name: 検索するオプションの名前

戻り値:

- オプションが見つかった場合はオプションへのポインタ、見つからなかった場合は NULL

C 言語での使用例:

    struct t_config_option *option =
        weechat_config_search_option (config_file, section, "option");

スクリプト (Python) での使用例:

    # プロトタイプ
    def config_search_option(config_file: str, section: str, option_name: str) -> str: ...

    # 例
    option = weechat.config_search_option(config_file, section, "option")

#### config_search_section_option

設定ファイルまたはセクションからセクションやオプションを検索。

プロトタイプ:

    void weechat_config_search_section_option (struct t_config_file *config_file,
                                               struct t_config_section *section,
                                               const char *option_name,
                                               struct t_config_section **section_found,
                                               struct t_config_option **option_found);

引数:

- config_file: 設定ファイルへのポインタ

- section: セクションへのポインタ

- option_name: オプション名

- section_found: セクションへのポインタへのポインタ、これは見つかったオプションのセクションになります

- option_found: オプションへのポインタへのポインタ、これは見つかったオプションのへのポインタになります

C 言語での使用例:

    struct t_config_section *ptr_section;
    struct t_config_option *ptr_option;

    weechat_config_search_section_option(config_file,
                                         section,
                                         "option",
                                         &ptr_section,
                                         &ptr_option);
    if (ptr_option)
    {
        /* option found */
    }
    else
    {
        /* option not found */
    }

注記 | スクリプト API ではこの関数を利用できません。

#### config_search_with_string

ファイル/セクション/オプションの情報をオプションを完全な名前で検索。

プロトタイプ:

    void weechat_config_search_with_string (const char *option_name,
                                            struct t_config_file **config_file,
                                            struct t_config_section **section,
                                            struct t_config_option **option,
                                            char **pos_option_name);

引数:

- option_name: オプションの完全な名前 (書式: "file.section.option")

- config_file: 設定ファイルへのポインタへのポインタ、これは見つかったオプションの設定ファイルへのポインタになります

- section: セクションへのポインタのポインタ、これは見つかったオプションのセクションになります

- option: オプションへのポインタのポインタ、これは見つかったオプションへのポインタになります

- pos_option_name: 文字列へのポインタへのポインタ、これはオプション名へのポインタになります

C 言語での使用例:

    struct t_config_file *ptr_config_file;
    struct t_config_section *ptr_section;
    struct t_config_option *ptr_option;
    char *option_name;

    weechat_config_search_with_string ("file.section.option",
                                       &ptr_config_file,
                                       &ptr_section,
                                       &ptr_option,
                                       &option_name);
    if (ptr_option)
    {
        /* option found */
    }
    else
    {
        /* option not found */
    }

注記 | スクリプト API ではこの関数を利用できません。

#### config_string_to_boolean

テキストがブール値としての "true" または "false" かをチェック。

プロトタイプ:

    int weechat_config_string_to_boolean (const char *text);

引数:

- text: チェックするテキスト

戻り値:

- テキストが "true" ("on"、"yes"、"y"、"true"、"t"、"1") の場合は 1

- テキストが "false" ("off"、"no"、"n"、"false"、"f"、"0") の場合は 0

C 言語での使用例:

    if (weechat_config_string_to_boolean (option_value))
    {
        /* value is "true" */
    }
    else
    {
        /* value is "false" */
    }

スクリプト (Python) での使用例:

    # プロトタイプ
    def config_string_to_boolean(text: str) -> int: ...

    # 例
    if weechat.config_string_to_boolean(text):
        # ...

#### config_option_reset

オプションをデフォルト値にリセット。

プロトタイプ:

    int weechat_config_option_reset (struct t_config_option *option,
                                     int run_callback);

引数:

- option: オプションへのポインタ

- run_callback: オプションを変更する際に、コールバックを呼び出す場合は 1、呼び出さない場合は 0

戻り値:

- オプションの値がリセットされた場合は WEECHAT_CONFIG_OPTION_SET_OK_CHANGED

- 値が変更されなかった場合は WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE

- エラーが起きた場合は WEECHAT_CONFIG_OPTION_SET_ERROR

C 言語での使用例:

    switch (weechat_config_option_reset (option, 1))
    {
        case WEECHAT_CONFIG_OPTION_SET_OK_CHANGED:
            /* .... */
            break;
        case WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE:
            /* .... */
            break;
        case WEECHAT_CONFIG_OPTION_SET_ERROR:
            /* .... */
            break;
    }

スクリプト (Python) での使用例:

    # プロトタイプ
    def config_option_reset(option: str, run_callback: int) -> int: ...

    # 例
    rc = weechat.config_option_reset(option, 1)
    if rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_CHANGED:
        # ...
    elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE:
        # ...
    elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_ERROR:
        # ...

#### config_option_set

オプションに新しい値を設定。

プロトタイプ:

    int weechat_config_option_set (struct t_config_option *option,
                                   const char *value, int run_callback);

引数:

- option: オプションへのポインタ

- value: オプションの新しい値、オプションのタイプによって以下の特殊値を取ることも可能です:

  - ブール型:

    - `toggle`: 現在の値を切り替える

  - integer, color or enum:

    - `++N`: 現在の値に `N` (任意の整数) を加える

    - `--N`: 現在の値から `N` (任意の整数) を引く

- run_callback: オプションが変更された際に、callback_change コールバックを呼び出す場合は 1、呼び出さない場合は 0

戻り値:

- オプションの値が変更された場合は WEECHAT_CONFIG_OPTION_SET_OK_CHANGED

- 値が変更されなかった場合は WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE

- エラーが起きた場合は WEECHAT_CONFIG_OPTION_SET_ERROR

C 言語での使用例:

    switch (weechat_config_option_set (option, "new_value", 1))
    {
        case WEECHAT_CONFIG_OPTION_SET_OK_CHANGED:
            /* .... */
            break;
        case WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE:
            /* .... */
            break;
        case WEECHAT_CONFIG_OPTION_SET_ERROR:
            /* .... */
            break;
    }

スクリプト (Python) での使用例:

    # プロトタイプ
    def config_option_set(option: str, value: str, run_callback: int) -> int: ...

    # 例
    rc = weechat.config_option_set(option, "new_value", 1)
    if rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_CHANGED:
        # ...
    elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE:
        # ...
    elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_ERROR:
        # ...

#### config_option_set_null

あるオプションに null (未定義値) を設定する。

プロトタイプ:

    int weechat_config_option_set_null (struct t_config_option *option,
                                        int run_callback);

引数:

- option: オプションへのポインタ

- run_callback: オプションが (null 以外の値に) 変更された際に、callback_change コールバックを呼び出す場合は 1、呼び出さない場合は 0

注記 | オプションに null を設定することが許可されている場合にのみ null を設定できます (config_new_option を参照)。

戻り値:

- オプション値が変更された場合は WEECHAT_CONFIG_OPTION_SET_OK_CHANGED

- 値が変更されなかった場合は WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE

- エラーが起きた場合は WEECHAT_CONFIG_OPTION_SET_ERROR

C 言語での使用例:

    switch (weechat_config_option_set_null (option, 1))
    {
        case WEECHAT_CONFIG_OPTION_SET_OK_CHANGED:
            /* .... */
            break;
        case WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE:
            /* .... */
            break;
        case WEECHAT_CONFIG_OPTION_SET_ERROR:
            /* .... */
            break;
    }

スクリプト (Python) での使用例:

    # プロトタイプ
    def config_option_set_null(option: str, run_callback: int) -> int: ...

    # 例
    rc = weechat.config_option_set_null(option, 1)
    if rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_CHANGED:
        # ...
    elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE:
        # ...
    elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_ERROR:
        # ...

#### config_option_unset

オプションをアンセット/リセットする。

プロトタイプ:

    int weechat_config_option_unset (struct t_config_option *option);

引数:

- option: オプションへのポインタ

戻り値:

- オプションの値がリセットされなかった場合は WEECHAT_CONFIG_OPTION_UNSET_OK_NO_RESET

- オプションの値がリセットされた場合は WEECHAT_CONFIG_OPTION_UNSET_OK_RESET

- オプションが削除された場合は WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED

- エラーが起きた場合は WEECHAT_CONFIG_OPTION_UNSET_ERROR

C 言語での使用例:

    switch (weechat_config_option_unset (option))
    {
        case WEECHAT_CONFIG_OPTION_UNSET_OK_NO_RESET:
            /* .... */
            break;
        case WEECHAT_CONFIG_OPTION_UNSET_OK_RESET:
            /* .... */
            break;
        case WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED:
            /* .... */
            break;
        case WEECHAT_CONFIG_OPTION_UNSET_ERROR:
            /* .... */
            break;
    }

スクリプト (Python) での使用例:

    # プロトタイプ
    def config_option_unset(option: str) -> int: ...

    # 例
    rc = weechat.config_option_unset(option)
    if rc == weechat.WEECHAT_CONFIG_OPTION_UNSET_OK_NO_RESET:
        # ...
    elif rc == weechat.WEECHAT_CONFIG_OPTION_UNSET_OK_RESET:
        # ...
    elif rc == weechat.WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED:
        # ...
    elif rc == weechat.WEECHAT_CONFIG_OPTION_UNSET_ERROR:
        # ...

#### config_option_rename

オプションをリネーム。

プロトタイプ:

    void weechat_config_option_rename (struct t_config_option *option,
                                       const char *new_name);

引数:

- option: オプションへのポインタ

- new_name: オプションの新しい名前

C 言語での使用例:

    weechat_config_option_rename (option, "new_name");

スクリプト (Python) での使用例:

    # プロトタイプ
    def config_option_rename(option: str, new_name: str) -> int: ...

    # 例
    weechat.config_option_rename(option, "new_name")

#### config_option_get_string

WeeChat バージョン 1.9 以上で利用可。

オプションプロパティの文字列値を返す。

プロトタイプ:

    const char *weechat_config_option_get_string (struct t_config_option *option,
                                                  const char *property);

引数:

- option: オプションへのポインタ

- property: プロパティ名:

  - config_name: ファイル名

  - section_name: セクション名

  - name: オプション名

  - parent_name: 親オプション名

  - type: オプション型、以下のリストのどれか 1 つ:

    - boolean

    - integer

    - string

    - color

    - enum

  - description: オプションの説明

戻り値:

- プロパティの文字列値

C 言語での使用例:

    const char *type = weechat_config_option_get_string (option, "type");

注記 | スクリプト API ではこの関数を利用できません。

#### config_option_get_pointer

あるオプションのプロパティへのポインタを返す。

プロトタイプ:

    void *weechat_config_option_get_pointer (struct t_config_option *option,
                                             const char *property);

引数:

- option: オプションへのポインタ

- property: プロパティ名:

  - config_file: 設定ファイルへのポインタ (struct t_config_file *)

  - section: セクションへのポインタ (struct t_config_section *)

  - name: オプション名 (char *)

  - parent_name: 親オプションの名前 (char *) (WeeChat バージョン 1.4 以上で利用可)

  - type: オプションの型 (int *)

  - description: オプションの説明 (char *)

  - string_values: 文字列値 (char *)

  - min: 最大値 (int *)

  - max: 最小値 (int *)

  - default_value: デフォルト値 (オプションの型に依存)

  - value: 現在の値 (オプションの型に依存)

  - prev_option: 1 つ前のオプションへのポインタ (struct t_config_option *)

  - next_option: 1 つ後のオプションへのポインタ (struct t_config_option *)

戻り値:

- 要求されたプロパティへのポインタ

C 言語での使用例:

    char *description = weechat_config_option_get_pointer (option, "description");

注記 | スクリプト API ではこの関数を利用できません。

#### config_option_is_null

オプションの値が "null" (未定義値) か否かを確認。

プロトタイプ:

    int weechat_config_option_is_null (struct t_config_option *option);

引数:

- option: オプションへのポインタ

戻り値:

- オプションの値が "null" の場合は 1

- オプションの値が "null" でない場合は 0

C 言語での使用例:

    if (weechat_config_option_is_null (option))
    {
        /* value is "null" */
    }
    else
    {
        /* value is not "null" */
    }

スクリプト (Python) での使用例:

    # プロトタイプ
    def config_option_is_null(option: str) -> int: ...

    # 例
    if weechat.config_option_is_null(option):
        # ...

#### config_option_default_is_null

あるオプションのデフォルト値が "null" (未定義値) か否かを確認。

プロトタイプ:

    int weechat_config_option_default_is_null (struct t_config_option *option);

引数:

- option: オプションへのポインタ

戻り値:

- オプションの値が "null" の場合は 1

- オプションの値が "null" でない場合は 0

C 言語での使用例:

    if (weechat_config_option_default_is_null (option))
    {
        /* default value is "null" */
    }
    else
    {
        /* default value is not "null" */
    }

スクリプト (Python) での使用例:

    # プロトタイプ
    def config_option_default_is_null(option: str) -> int: ...

    # 例
    if weechat.config_option_default_is_null(option):
        # ...

#### config_boolean

オプションのブール値を返す。

プロトタイプ:

    int weechat_config_boolean (struct t_config_option *option);

引数:

- option: オプションへのポインタ

戻り値、オプションの型に依存:

- boolean: オプションのブール値 (0 または 1)

- integer: 0

- string: 0

- color: 0

- enum: 0

C 言語での使用例:

    struct t_config_option *option = weechat_config_get ("plugin.section.option");
    if (weechat_config_boolean (option))
    {
        /* value is "true" */
    }
    else
    {
        /* value is "false" */
    }

スクリプト (Python) での使用例:

    # プロトタイプ
    def config_boolean(option: str) -> int: ...

    # 例
    option = weechat.config_get("plugin.section.option")
    if weechat.config_boolean(option):
        # ...

#### config_boolean_default

オプションのデフォルトブール値を返す。

プロトタイプ:

    int weechat_config_boolean_default (struct t_config_option *option);

引数:

- option: オプションへのポインタ

戻り値、オプションの型に依存:

- boolean: オプションのデフォルトブール値 (0 または 1)

- integer: 0

- string: 0

- color: 0

- enum: 0

C 言語での使用例:

    struct t_config_option *option = weechat_config_get ("plugin.section.option");
    if (weechat_config_boolean_default (option))
    {
        /* value is "true" */
    }
    else
    {
        /* value is "false" */
    }

スクリプト (Python) での使用例:

    # プロトタイプ
    def config_boolean_default(option: str) -> int: ...

    # 例
    option = weechat.config_get("plugin.section.option")
    if weechat.config_boolean_default(option):
        # ...

#### config_boolean_inherited

WeeChat ≥ 4.3.0.

Return inherited boolean value of option: value of option if not NULL, or value of the parent option (if option inherits from another option).
If the parent option is not found, return the default value of the option.
If the parent value is NULL, return the default value of the parent option.

プロトタイプ:

    int weechat_config_boolean_inherited (struct t_config_option *option);

引数:

- option: オプションへのポインタ

Return value: see functions config_boolean and config_boolean_default.

C 言語での使用例:

    struct t_config_option *option = weechat_config_get ("irc.server.libera.autoconnect");
    int autoconnect = weechat_config_boolean_inherited (option);

スクリプト (Python) での使用例:

    # プロトタイプ
    def config_boolean_inherited(option: str) -> int: ...

    # 例
    option = weechat.config_get("irc.server.libera.autoconnect")
    autoconnect = weechat.config_boolean_inherited(option)

#### config_integer

オプションの整数値を返す。

プロトタイプ:

    int weechat_config_integer (struct t_config_option *option);

引数:

- option: オプションへのポインタ

戻り値、オプションの型に依存:

- boolean: オプションのブール値 (0 または 1)

- integer: オプションの整数値

- string: 0

- color: 色インデックス

- enum: integer value of option (index of enum value)

C 言語での使用例:

    struct t_config_option *option = weechat_config_get ("plugin.section.option");
    int value = weechat_config_integer (option);

スクリプト (Python) での使用例:

    # プロトタイプ
    def config_integer(option: str) -> int: ...

    # 例
    option = weechat.config_get("plugin.section.option")
    value = weechat.config_integer(option)

#### config_integer_default

オプションのデフォルト整数値を返す。

プロトタイプ:

    int weechat_config_integer_default (struct t_config_option *option);

引数:

- option: オプションへのポインタ

戻り値、オプションの型に依存:

- boolean: オプションのデフォルトブール値 (0 または 1)

- integer: オプションのデフォルト整数値

- string: 0

- color: デフォルト色インデックス

- enum: default integer value of option (index of enum value)

C 言語での使用例:

    struct t_config_option *option = weechat_config_get ("plugin.section.option");
    int value = weechat_config_integer_default (option);

スクリプト (Python) での使用例:

    # プロトタイプ
    def config_integer_default(option: str) -> int: ...

    # 例
    option = weechat.config_get("plugin.section.option")
    value = weechat.config_integer_default(option)

#### config_integer_inherited

WeeChat ≥ 4.3.0.

Return inherited integer value of option: value of option if not NULL, or value of the parent option (if option inherits from another option).
If the parent option is not found, return the default value of the option.
If the parent value is NULL, return the default value of the parent option.

プロトタイプ:

    int weechat_config_integer_inherited (struct t_config_option *option);

引数:

- option: オプションへのポインタ

Return value: see functions config_integer and config_integer_default.

C 言語での使用例:

    struct t_config_option *option = weechat_config_get ("irc.server.libera.autojoin_delay");
    int delay = weechat_config_integer_inherited (option);

スクリプト (Python) での使用例:

    # プロトタイプ
    def config_integer_inherited(option: str) -> int: ...

    # 例
    option = weechat.config_get("irc.server.libera.autojoin_delay")
    delay = weechat.config_integer_inherited(option)

#### config_string

オプションの文字列値を返す。

プロトタイプ:

    const char *weechat_config_string (struct t_config_option *option);

引数:

- option: オプションへのポインタ

戻り値、オプションの型に依存:

- boolean: 値が真の場合は "on"、それ以外の場合は "off"

- integer: NULL

- string: オプションの文字列値

- color: 色名

- enum: string value of option

C 言語での使用例:

    struct t_config_option *option = weechat_config_get ("plugin.section.option");
    const char *value = weechat_config_string (option);

スクリプト (Python) での使用例:

    # プロトタイプ
    def config_string(option: str) -> str: ...

    # 例
    option = weechat.config_get("plugin.section.option")
    value = weechat.config_string(option)

#### config_string_default

オプションのデフォルト文字列値を返す。

プロトタイプ:

    const char *weechat_config_string_default (struct t_config_option *option);

引数:

- option: オプションへのポインタ

戻り値、オプションの型に依存:

- boolean: デフォルト値が真の場合は "on"、それ以外の場合は "off"

- integer: NULL

- string: オプションのデフォルト文字列値

- color: デフォルト色名

- enum: default string value of option

C 言語での使用例:

    struct t_config_option *option = weechat_config_get ("plugin.section.option");
    const char *value = weechat_config_string_default (option);

スクリプト (Python) での使用例:

    # プロトタイプ
    def config_string_default(option: str) -> str: ...

    # 例
    option = weechat.config_get("plugin.section.option")
    value = weechat.config_string_default(option)

#### config_string_inherited

WeeChat ≥ 4.3.0.

Return inherited string value of option: value of option if not NULL, or value of the parent option (if option inherits from another option).
If the parent option is not found, return the default value of the option.
If the parent value is NULL, return the default value of the parent option.

プロトタイプ:

    const char *weechat_config_string_inherited (struct t_config_option *option);

引数:

- option: オプションへのポインタ

Return value: see functions config_string and config_string_default.

C 言語での使用例:

    struct t_config_option *option = weechat_config_get ("irc.server.libera.msg_quit");
    const char *msg_quit = weechat_config_string_inherited (option);

スクリプト (Python) での使用例:

    # プロトタイプ
    def config_string_inherited(option: str) -> str: ...

    # 例
    option = weechat.config_get("irc.server.libera.msg_quit")
    msg_quit = weechat.config_string_inherited(option)

#### config_color

オプションの色値を返す。

プロトタイプ:

    const char *weechat_config_color (struct t_config_option *option);

引数:

- option: オプションへのポインタ

戻り値、オプションの型に依存:

- boolean: NULL

- integer: NULL

- string: NULL

- color: 色名

- enum: NULL

C 言語での使用例:

    struct t_config_option *option = weechat_config_get ("plugin.section.option");
    const char *color = weechat_config_color (option);

スクリプト (Python) での使用例:

    # プロトタイプ
    def config_color(option: str) -> str: ...

    # 例
    option = weechat.config_get("plugin.section.option")
    color = weechat.config_color(option)

#### config_color_default

オプションのデフォルト色値を返す。

プロトタイプ:

    const char *weechat_config_color_default (struct t_config_option *option);

引数:

- option: オプションへのポインタ

戻り値、オプションの型に依存:

- boolean: NULL

- integer: NULL

- string: NULL

- color: デフォルト色名

- enum: NULL

C 言語での使用例:

    struct t_config_option *option = weechat_config_get ("plugin.section.option");
    const char *color = weechat_config_color_default (option);

スクリプト (Python) での使用例:

    # プロトタイプ
    def config_color_default(option: str) -> str: ...

    # 例
    option = weechat.config_get("plugin.section.option")
    color = weechat.config_color_default(option)

#### config_color_inherited

WeeChat ≥ 4.3.0.

Return inherited color value of option: value of option if not NULL, or value of the parent option (if option inherits from another option).
If the parent option is not found, return the default value of the option.
If the parent value is NULL, return the default value of the parent option.

プロトタイプ:

    const char *weechat_config_color_inherited (struct t_config_option *option);

引数:

- option: オプションへのポインタ

Return value: see functions config_color and config_color_default.

C 言語での使用例:

    struct t_config_option *option = weechat_config_get ("plugin.section.option");
    const char *color = weechat_config_color_inherited (option);

スクリプト (Python) での使用例:

    # プロトタイプ
    def config_color_inherited(option: str) -> str: ...

    # 例
    option = weechat.config_get("plugin.section.option")
    color = weechat.config_color_inherited(option)

#### config_enum

WeeChat ≥ 4.1.0.

Return enum value of option, as integer.

Prototype:

    int weechat_config_enum (struct t_config_option *option);

Arguments:

- option: option pointer

Return value, depending on the option type:

- boolean: boolean value of option (0 or 1)

- integer: integer value of option

- string: 0

- color: color index

- enum: integer value of option (index of enum value)

C example:

    struct t_config_option *option = weechat_config_get ("plugin.section.option");
    int value = weechat_config_enum (option);

Script (Python):

    # prototype
    def config_enum(option: str) -> int: ...

    # example
    option = weechat.config_get("plugin.section.option")
    value = weechat.config_enum(option)

#### config_enum_default

WeeChat ≥ 4.1.0.

Return default enum value of option, as integer.

Prototype:

    int weechat_config_enum_default (struct t_config_option *option);

Arguments:

- option: option pointer

Return value, depending on the option type:

- boolean: default boolean value of option (0 or 1)

- integer: default integer value of option

- string: 0

- color: default color index

- enum: integer value of option (index of enum value)

C example:

    struct t_config_option *option = weechat_config_get ("plugin.section.option");
    int value = weechat_config_enum_default (option);

Script (Python):

    # prototype
    def config_enum_default(option: str) -> int: ...

    # example
    option = weechat.config_get("plugin.section.option")
    value = weechat.config_enum_default(option)

#### config_enum_inherited

WeeChat ≥ 4.3.0.

Return inherited enum value of option: value of option if not NULL, or value of the parent option (if option inherits from another option).
If the parent option is not found, return the default value of the option.
If the parent value is NULL, return the default value of the parent option.

プロトタイプ:

    int weechat_config_enum_inherited (struct t_config_option *option);

引数:

- option: オプションへのポインタ

Return value: see functions config_enum and config_enum_default.

C 言語での使用例:

    struct t_config_option *option = weechat_config_get ("irc.server.libera.sasl_fail");
    int sasl_fail = weechat_config_enum_inherited (option);

スクリプト (Python) での使用例:

    # プロトタイプ
    def config_enum_inherited(option: str) -> int: ...

    # 例
    option = weechat.config_get("irc.server.libera.sasl_fail")
    sasl_fail = weechat.config_enum_inherited(option)

#### config_write_option

設定ファイルにオプションとその値を収めた行を書き込む (この関数をセクションの "write" および "write_default" コールバック以外で使わないでください)。

プロトタイプ:

    void weechat_config_write_option (struct t_config_file *config_file,
                                      struct t_config_option *option);

引数:

- config_file: 設定ファイルへのポインタ

- option: オプションへのポインタ

C 言語での使用例:

    int
    my_section_write_cb (const void *pointer, void *data,
                         struct t_config_file *config_file,
                         const char *section_name)
    {
        weechat_config_write_line (config_file, "my_section", NULL);

        weechat_config_write_option (config_file, option);

        return WEECHAT_RC_OK;
    }

スクリプト (Python) での使用例:

    # プロトタイプ
    def config_write_option(config_file: str, option: str) -> int: ...

    # 例
    def my_section_write_cb(data: str, config_file: str, section_name: str) -> int:
        weechat.config_write_line(config_file, "my_section", "")
        weechat.config_write_option(config_file, option)
        return weechat.WEECHAT_RC_OK

#### config_write_line

設定ファイルに行を書き込む (この関数をセクションの "write" および "write_default" コールバック以外で使わないでください)

プロトタイプ:

    void weechat_config_write_line (struct t_config_file *config_file,
                                    const char *option_name,
                                    const char *value, ...);

引数:

- config_file: 設定ファイルへのポインタ

- option_name: オプション名

- value: 値 (NULL の場合、セクション名の行を書き込みます。例: "[section]")

C 言語での使用例:

    int
    my_section_write_cb (const void *pointer, void *data,
                         struct t_config_file *config_file,
                         const char *section_name)
    {
        weechat_config_write_line (config_file, "my_section", NULL);

        weechat_config_write_line (config_file, "option", "%s;%d",
                                   "value", 123);

        return WEECHAT_RC_OK;
    }

スクリプト (Python) での使用例:

    # プロトタイプ
    def config_write_line(config_file: str, option_name: str, value: str) -> int: ...

    # 例
    def my_section_write_cb(data: str, config_file: str, section_name: str) -> int:
        weechat.config_write_line(config_file, "my_section", "")
        weechat.config_write_line(config_file, "option", "value")
        return weechat.WEECHAT_RC_OK

#### config_write

設定ファイルをディスクに書き込む。

プロトタイプ:

    int weechat_config_write (struct t_config_file *config_file);

引数:

- config_file: 設定ファイルへのポインタ

戻り値:

- 設定を書き込んだ場合は WEECHAT_CONFIG_WRITE_OK

- メモリ不足の場合は WEECHAT_CONFIG_WRITE_MEMORY_ERROR

- その他のエラーが起きた場合は WEECHAT_CONFIG_WRITE_ERROR

C 言語での使用例:

    switch (weechat_config_write (config_file))
    {
        case WEECHAT_CONFIG_WRITE_OK:
            /* ... */
            break;
        case WEECHAT_CONFIG_WRITE_MEMORY_ERROR:
            /* ... */
            break;
        case WEECHAT_CONFIG_WRITE_ERROR:
            /* ... */
            break;
    }

スクリプト (Python) での使用例:

    # プロトタイプ
    def config_write(config_file: str) -> int: ...

    # 例
    rc = weechat.config_write(config_file)
    if rc == weechat.WEECHAT_CONFIG_WRITE_OK:
        # ...
    elif rc == weechat.WEECHAT_CONFIG_WRITE_MEMORY_ERROR:
        # ...
    elif rc == weechat.WEECHAT_CONFIG_WRITE_ERROR:
        # ...

#### config_read

設定ファイルをディスクから読み込む。

プロトタイプ:

    int weechat_config_read (struct t_config_file *config_file);

引数:

- config_file: 設定ファイルへのポインタ

戻り値:

- 設定ファイルを読み込んだ場合は WEECHAT_CONFIG_READ_OK

- メモリ不足の場合は WEECHAT_CONFIG_READ_MEMORY_ERROR

- ファイルが見つからない場合は WEECHAT_CONFIG_READ_FILE_NOT_FOUND

C 言語での使用例:

    switch (weechat_config_read (config_file))
    {
        case WEECHAT_CONFIG_READ_OK:
            /* ... */
            break;
        case WEECHAT_CONFIG_READ_MEMORY_ERROR:
            /* ... */
            break;
        case WEECHAT_CONFIG_READ_FILE_NOT_FOUND:
            /* ... */
            break;
    }

スクリプト (Python) での使用例:

    # プロトタイプ
    def config_read(config_file: str) -> int: ...

    # 例
    rc = weechat.config_read(config_file)
    if rc == weechat.WEECHAT_CONFIG_READ_OK:
        # ...
    elif rc == weechat.WEECHAT_CONFIG_READ_MEMORY_ERROR:
        # ...
    elif rc == weechat.WEECHAT_CONFIG_READ_FILE_NOT_FOUND:
        # ...

#### config_reload

設定ファイルをディスクからリロードする。

プロトタイプ:

    int weechat_config_reload (struct t_config_file *config_file);

引数:

- config_file: 設定ファイルへのポインタ

戻り値:

- 設定をリロードした場合は WEECHAT_CONFIG_READ_OK

- メモリ不足の合は WEECHAT_CONFIG_READ_MEMORY_ERROR

- ファイルが見つからない場合は WEECHAT_CONFIG_READ_FILE_NOT_FOUND

C 言語での使用例:

    switch (weechat_config_reload (config_file))
    {
        case WEECHAT_CONFIG_READ_OK:
            /* ... */
            break;
        case WEECHAT_CONFIG_READ_MEMORY_ERROR:
            /* ... */
            break;
        case WEECHAT_CONFIG_READ_FILE_NOT_FOUND:
            /* ... */
            break;
    }

スクリプト (Python) での使用例:

    # プロトタイプ
    def config_reload(config_file: str) -> int: ...

    # 例
    rc = weechat.config_reload(config_file)
    if rc == weechat.WEECHAT_CONFIG_READ_OK:
        # ...
    elif rc == weechat.WEECHAT_CONFIG_READ_MEMORY_ERROR:
        # ...
    elif rc == weechat.WEECHAT_CONFIG_READ_FILE_NOT_FOUND:
        # ...

#### config_option_free

オプションを開放。

プロトタイプ:

    void weechat_config_option_free (struct t_config_option *option);

引数:

- option: オプションへのポインタ

C 言語での使用例:

    weechat_config_option_free (option);

スクリプト (Python) での使用例:

    # プロトタイプ
    def config_option_free(option: str) -> int: ...

    # 例
    weechat.config_option_free(option)

#### config_section_free_options

セクションの全てのオプションを開放。

プロトタイプ:

    void weechat_config_section_free_options (struct t_config_section *section);

引数:

- section: セクションへのポインタ

C 言語での使用例:

    weechat_config_section_free_options (section);

スクリプト (Python) での使用例:

    # プロトタイプ
    def config_section_free_options(section: str) -> int: ...

    # 例
    weechat.config_section_free_options(section)

#### config_section_free

セクションを開放。

プロトタイプ:

    void weechat_config_section_free (struct t_config_section *section);

引数:

- section: セクションへのポインタ

C 言語での使用例:

    weechat_config_section_free (section);

スクリプト (Python) での使用例:

    # プロトタイプ
    def config_section_free(section: str) -> int: ...

    # 例
    weechat.config_section_free(section)

#### config_free

設定ファイルを開放。

プロトタイプ:

    void weechat_config_free (struct t_config_file *config_file);

引数:

- config_file: 設定ファイルへのポインタ

C 言語での使用例:

    weechat_config_free (config_file);

スクリプト (Python) での使用例:

    # プロトタイプ
    def config_free(config_file: str) -> int: ...

    # 例
    weechat.config_free(config_file)

#### config_get

完全な名前でオプションを検索。

プロトタイプ:

    struct t_config_option *weechat_config_get (const char *option_name);

引数:

- option_name: オプションの完全な名前 (書式: "file.section.option")

戻り値:

- 見つかったオプションへのポインタ、見つからなかった場合は NULL

C 言語での使用例:

    struct t_config_option *option = weechat_config_get ("weechat.look.item_time_format");

スクリプト (Python) での使用例:

    # プロトタイプ
    def config_get(option_name: str) -> str: ...

    # 例
    option = weechat.config_get("weechat.look.item_time_format")

#### config_get_plugin

プラグインの設定ファイル (plugins.conf) からオプションを検索。

プロトタイプ:

    const char *weechat_config_get_plugin (const char *option_name);

引数:

- option_name: オプション名、プレフィックス "plugins.var.xxx." が自動的に付けられる (ここで "xxx" は現在のプラグイン名)。

戻り値:

- 見つかったオプションの値、オプションが見つからなければ NULL

C 言語での使用例:

    /* if current plugin is "test", then look for value of option
       "plugins.var.test.option" in file plugins.conf */
    char *value = weechat_config_get_plugin ("option");

スクリプト (Python) での使用例:

    # プロトタイプ
    def config_get_plugin(option_name: str) -> str: ...

    # 例
    value = weechat.config_get_plugin("option")

#### config_is_set_plugin

オプションがプラグインの設定ファイル (plugins.conf) で設定されているか否かを確認。

プロトタイプ:

    int weechat_config_is_set_plugin (const char *option_name);

引数:

- option_name: オプション名、プレフィックス "plugins.var.xxx." が自動的に付けられる (ここで "xxx" は現在のプラグイン名)。

戻り値:

- オプションが設定されている場合は 1、オプションが存在しない場合は 0

C 言語での使用例:

    if (weechat_config_is_set_plugin ("option"))
    {
        /* option is set */
    }
    else
    {
        /* option does not exist */
    }

スクリプト (Python) での使用例:

    # プロトタイプ
    def config_is_set_plugin(option_name: str) -> int: ...

    # 例
    if weechat.config_is_set_plugin("option"):
        # option is set
        # ...
    else:
        # option does not exist
        # ...

#### config_set_plugin

プラグイン設定ファイル (plugins.conf) のオプションの新しい値を設定。

プロトタイプ:

    int weechat_config_set_plugin (const char *option_name, const char *value);

引数:

- option_name: オプション名、プレフィックス "plugins.var.xxx." が自動的に付けられる (ここで "xxx" は現在のプラグイン名)。

- value: オプションの新しい値

戻り値:

- オプションの値を変更した場合は WEECHAT_CONFIG_OPTION_SET_OK_CHANGED

- 値を変更しなかった場合は WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE

- オプションが見つからない場合は WEECHAT_CONFIG_OPTION_SET_OPTION_NOT_FOUND

- その他のエラーが起きた場合は WEECHAT_CONFIG_OPTION_SET_ERROR

C 言語での使用例:

    switch (weechat_config_set_plugin ("option", "test_value"))
    {
        case WEECHAT_CONFIG_OPTION_SET_OK_CHANGED:
            /* ... */
            break;
        case WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE:
            /* ... */
            break;
        case WEECHAT_CONFIG_OPTION_SET_OPTION_NOT_FOUND:
            /* ... */
            break;
        case WEECHAT_CONFIG_OPTION_SET_ERROR:
            /* ... */
            break;
    }

スクリプト (Python) での使用例:

    # プロトタイプ
    def config_set_plugin(option_name: str, value: str) -> int: ...

    # 例
    rc = weechat.config_set_plugin("option", "test_value")
    if rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_CHANGED:
        # ...
    elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE:
        # ...
    elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_OPTION_NOT_FOUND:
        # ...
    elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_ERROR:
        # ...

#### config_set_desc_plugin

WeeChat バージョン 0.3.5 以上で利用可。

プラグイン設定ファイル (plugins.conf) のオプションに関する説明を設定。

プロトタイプ:

    void weechat_config_set_desc_plugin (const char *option_name,
                                         const char *description);

引数:

- option_name: オプション名、プレフィックス "plugins.var.xxx." が自動的に付けられる (ここで "xxx" は現在のプラグイン名)。

- description: オプションの説明

注記 | オプション (plugins.var.xxx.option_name) が存在しなくても問題ありません。この説明を持つような名前のオプションが作成されます。

C 言語での使用例:

    weechat_config_set_desc_plugin ("option", "description of option");

スクリプト (Python) での使用例:

    # プロトタイプ
    def config_set_desc_plugin(option_name: str, description: str) -> int: ...

    # 例
    version = weechat.info_get("version_number", "") or 0
    if int(version) >= 0x00030500:
        weechat.config_set_desc_plugin("option", "description of option")

#### config_unset_plugin

プラグイン設定ファイル (plugins.conf) のオプションをアンセットする。

プロトタイプ:

    int weechat_config_unset_plugin (const char *option_name);

引数:

- option_name: オプション名、プレフィックス "plugins.var.xxx." が自動的に付けられる (ここで "xxx" は現在のプラグイン名)。

戻り値:

- オプションの値をリセットしなかった場合は WEECHAT_CONFIG_OPTION_UNSET_OK_NO_RESET

- オプションの値をリセットした場合は WEECHAT_CONFIG_OPTION_UNSET_OK_RESET

- オプションを削除した場合は WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED

- エラーが起きた場合は WEECHAT_CONFIG_OPTION_UNSET_ERROR

C 言語での使用例:

    switch (weechat_config_unset_plugin ("option"))
    {
        case WEECHAT_CONFIG_OPTION_UNSET_OK_NO_RESET:
            /* ... */
            break;
        case WEECHAT_CONFIG_OPTION_UNSET_OK_RESET:
            /* ... */
            break;
        case WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED:
            /* ... */
            break;
        case WEECHAT_CONFIG_OPTION_UNSET_ERROR:
            /* ... */
            break;
    }

スクリプト (Python) での使用例:

    # プロトタイプ
    def config_unset_plugin(option_name: str) -> int: ...

    # 例
    rc = weechat.config_unset_plugin("option")
    if rc == weechat.WEECHAT_CONFIG_OPTION_UNSET_OK_NO_RESET:
        # ...
    elif rc == weechat.WEECHAT_CONFIG_OPTION_UNSET_OK_RESET:
        # ...
    elif rc == weechat.WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED:
        # ...
    elif rc == weechat.WEECHAT_CONFIG_OPTION_UNSET_ERROR:
        # ...

### 3.12. キー割り当て

キー割り当てに関する関数。

#### key_bind

WeeChat バージョン 0.3.6 以上で利用可、バージョン 1.8 で更新。

新しいキー割り当てを追加。

注記 | コマンド `/key bind` とは異なり、この関数がすでに存在しているキー割り当てを変更することはありません。新しいキー割り当てを作成するだけです。キー割り当てを削除するには key_unbind を使ってください。

プロトタイプ:

    int weechat_key_bind (const char *context, struct t_hashtable *keys);

引数:

- context: キーのコンテキスト:

  - default: デフォルトコンテキスト (一般的な動作)

  - search: 検索コンテキスト (バッファ中のテキストを検索中)

  - cursor: 画面上のカーソルを自由に移動

  - mouse: マウスイベント用のキー

- keys: キー割り当てを収めたハッシュテーブル; 以下の特殊キーを収めることが可能です:

  - __quiet: コアバッファに追加されたキーを表示しない (WeeChat バージョン 1.8 以上で利用可)

戻り値:

- 追加されたキー割り当て

C 言語での使用例:

    struct t_hashtable *keys = weechat_hashtable_new (8,
                                                      WEECHAT_HASHTABLE_STRING,
                                                      WEECHAT_HASHTABLE_STRING,
                                                      NULL,
                                                      NULL);
    if (keys)
    {
        weechat_hashtable_set (keys, "@chat(plugin.buffer):button1", "hsignal:test_mouse");
        weechat_hashtable_set (keys, "@chat(plugin.buffer):wheelup", "/mycommand up");
        weechat_hashtable_set (keys, "@chat(plugin.buffer):wheeldown", "/mycommand down");
        weechat_key_bind ("mouse", keys);
        weechat_hashtable_free (keys);
    }

スクリプト (Python) での使用例:

    # プロトタイプ
    def key_bind(context: str, keys: Dict[str, str]) -> int: ...

    # 例
    keys = {"@chat(python.test):button1": "hsignal:test_mouse",
            "@chat(python.test):wheelup": "/mycommand up",
            "@chat(python.test):wheeldown": "/mycommand down"}
    weechat.key_bind("mouse", keys)

#### key_unbind

WeeChat バージョン 0.3.6 以上で利用可、バージョン 2.0 で更新。

キー割り当てを削除。

注意 | この関数を呼び出す際には、ユーザのキー割り当てを削除しないように注意してください。

プロトタイプ:

    int weechat_key_unbind (const char *context, const char *key);

引数:

- context: キーのコンテキスト (key_bind を参照)

- key: 削除するキーまたは特殊値 "area:XXX" で1 番目または 2 番目の領域から XXX をもつすべてのキーを削除しますが、 キーの先頭に "quiet:" を付けた場合には、削除されたキーを core バッファに表示しません (WeeChat バージョン 2.0 以上で利用可)。

戻り値:

- 削除されたキー割り当ての個数

C 言語での使用例:

    /* remove a single key */
    weechat_key_unbind ("mouse", "@chat(plugin.buffer):button1");

    /* remove all keys with area "chat(plugin.buffer)" */
    weechat_key_unbind ("mouse", "area:chat(plugin.buffer)");

スクリプト (Python) での使用例:

    # プロトタイプ
    def key_unbind(context: str, key: str) -> int: ...

    # 例

    # remove a single key
    weechat.key_unbind("mouse", "@chat(plugin.buffer):button1")

    # remove all keys with area "chat(python.test)"
    weechat.key_unbind("mouse", "area:chat(python.test)")

### 3.13. 表示

バッファにテキストを表示する関数。

#### prefix

プレフィックスを返す。

プロトタイプ:

    const char *weechat_prefix (const char *prefix);

引数:

- prefix: プレフィックスの名前 (以下の表を参照)

戻り値:

- プレフィックスの値 (プレフィックスと色コードを含む文字列)、プレフィックスが見つからない場合は空文字列

List of prefixes:

プレフィックス | 値 | 色 | 説明
--- | --- | --- | ---
`error` | `=!=` | yellow | エラーメッセージ
`network` | `--` | magenta | ネットワークからのメッセージ
`action` | `*` | white | 本人の動作
`join` | `-->` | lightgreen | 誰かが現在のチャットに参加
`quit` | `<--` | lightred | 誰かが現在のチャットから退出

注記 | 値と色はコマンド `/set` でカスタマイズできます。

C 言語での使用例:

    weechat_printf (NULL, "%sThis is an error...", weechat_prefix ("error"));

スクリプト (Python) での使用例:

    # プロトタイプ
    def prefix(prefix: str) -> str: ...

    # 例
    weechat.prnt("", "%sThis is an error..." % weechat.prefix("error"))

#### color

表示する色コードを文字列で返す。

プロトタイプ:

    const char *weechat_color (const char *color_name);

引数:

- color_name: 色の名前、以下の中から 1 つ:

  - WeeChat 色オプション名 (weechat.color.xxx の xxx)、例えば chat_delimiters

  - オプション名 (書式: file.section.option)、例えば irc.color.message_quit (WeeChat バージョン 1.2 以上で利用可)

  - 任意で属性や背景色を指定した色 (以下を参照)

  - 属性:

    - blink: set blink

    - -blink: remove blink

    - dim: set "dim" (half bright)

    - -dim: remove "dim" (half bright)

    - bold: 太字を有効

    - -bold: 太字を無効

    - reverse: 色反転を有効

    - -reverse: 色反転を削除

    - italic: イタリックを有効

    - -italic: イタリックを無効

    - underline: 下線を有効

    - -underline: 下線を無効

    - emphasis: テキストの強調を切り替え (注意: WeeChat はテキスト強調をバッファテキストを検索する際に使用するため、バー以外でこれを使わないでください。) (WeeChat バージョン 0.4.2 以上で利用可)

  - バーの色名:

    - bar_fg: バーのテキストの色

    - bar_delim: バーの区切り文字の色

    - bar_bg: バーの背景色

  - リセット:

    - reset: 色と属性をリセット

    - resetcolor: 色をリセット (属性はリセットしない) (WeeChat バージョン 0.3.6 以上で利用可)

色の書式: 属性 (任意) + 色名 + ",background" (任意)。以下の属性を使えます:

- `%`: blink

- `.`: "dim" (half bright)

- `*` : 太字

- `!` : 色反転

- `/` : イタリック

- `_` : 下線

- `|` : 属性を保存: 色を変更する際に太字/色反転/イタリック/下線の状態をリセットしない (WeeChat バージョン 0.3.6 以上で利用可)

例:

- `yellow` : テキストを黄色に

- `_green` : テキストに下線を引き、テキストを緑色に

- `*214` : テキストを太字でオレンジ色に

- `yellow,red` : テキストを黄色に、背景色を赤に

- `|cyan` : テキストをシアンに (これよりも前に設定した属性は変えない)

戻り値:

- 色コードを収めた文字列、色が見つからない場合は空文字列

C 言語での使用例:

    weechat_printf (NULL, "Color: %sblue %sdefault color %syellow on red",
                    weechat_color ("blue"),
                    weechat_color ("chat"),
                    weechat_color ("yellow,red"));

スクリプト (Python) での使用例:

    # プロトタイプ
    def color(color_name: str) -> str: ...

    # 例
    weechat.prnt("", "Color: %sblue %sdefault color %syellow on red"
        % (weechat.color("blue"), weechat.color("chat"), weechat.color("yellow,red")))

#### printf

バッファにメッセージを表示。

プロトタイプ:

    void weechat_printf (struct t_gui_buffer *buffer, const char *message, ...);

この関数は printf_datetime_tags 関数の別名です。以下に示す通り、どちらの関数も同じ結果を返します:

    weechat_printf (buffer, "message");
    weechat_printf_datetime_tags (buffer, 0, 0, NULL, "message");

引数:

- buffer: バッファへのポインタ、NULL の場合は WeeChat バッファにメッセージを表示

- message: 表示するメッセージ

注記 | メッセージに含まれる最初のタブ文字 ("\t") はメッセージのプレフィックスを分割するために使われます。 メッセージに複数のタブ文字が含まれ、プレフィックスを使いたくない場合は、空白、タブ文字、メッセージのように使ってください (以下の例を参照): これでプレフィックスが無くなります (タブ文字の前の空白は表示されません)。

注記 | 2 つ連続したタブ文字 ("\t") がメッセージの最初にある場合、時刻は表示されず、メッセージの位置調整は行われません。さらにメッセージの時刻が 0 に設定されます。

C 言語での使用例:

    weechat_printf (NULL, "Hello on WeeChat buffer");
    weechat_printf (buffer, "Hello on this buffer");
    weechat_printf (buffer, "%sThis is an error!", weechat_prefix ("error"));
    weechat_printf (buffer, " \tMessage without prefix but with \t some \t tabs");
    weechat_printf (buffer, "\t\tMessage without time/alignment");
    weechat_printf (buffer, "\t\t");  /* empty line (without time) */

スクリプト (Python) での使用例:

    # プロトタイプ
    def prnt(buffer: str, message: str) -> int: ...

    # 例
    weechat.prnt("", "Hello on WeeChat buffer")
    weechat.prnt(buffer, "Hello on this buffer")
    weechat.prnt(buffer, "%sThis is an error!" % weechat.prefix("error"))
    weechat.prnt(buffer, " \tMessage without prefix but with \t some \t tabs")
    weechat.prnt(buffer, "\t\tMessage without time/alignment")
    weechat.prnt(buffer, "\t\t")  # empty line (without time)

注記 | この関数をスクリプトの中で実行するには "print" (Python の場合は "prnt") と書きます。

#### printf_date_tags

日付とタグを指定してバッファにメッセージを表示。

プロトタイプ:

    void weechat_printf_date_tags (struct t_gui_buffer *buffer, time_t date,
                                   const char *tags, const char *message, ...);

この関数は printf_datetime_tags 関数の別名です。以下に示す通り、どちらの関数も同じ結果を返します:

    weechat_printf_date_tags (buffer, 0, NULL, "message");
    weechat_printf_datetime_tags (buffer, 0, 0, NULL, "message");

引数:

- buffer: バッファへのポインタ、NULL の場合、メッセージは WeeChat バッファに表示

- date: メッセージの日付 (0 は現在の日付/時間を意味する)

- tags: タグのコンマ区切りリスト (タグを指定しない場合は NULL)

- message: 表示するメッセージ

WeeChat で共通に使われるタグのリストは WeeChat ユーザーズガイド / 行のタグ ↗を参照してください

C 言語での使用例:

    weechat_printf_date_tags (NULL, time (NULL) - 120, "notify_message",
                              "Message 2 minutes ago, with a tag 'notify_message'");

スクリプト (Python) での使用例:

    # プロトタイプ
    def prnt_date_tags(buffer: str, date: int, tags: str, message: str) -> int: ...

    # 例
    time = int(time.time())
    weechat.prnt_date_tags("", time - 120, "notify_message",
        "Message 2 minutes ago, with a tag 'notify_message'")

注記 | この関数をスクリプトの中で実行するには "print_date_tags" (Python の場合は "prnt_date_tags") と書きます。

#### printf_datetime_tags

WeeChat ≥ 4.2.0.

Display a message on a buffer, using a custom date/time (with microseconds) and tags.

プロトタイプ:

    void weechat_printf_datetime_tags (struct t_gui_buffer *buffer, time_t date,
                                       int date_usec, const char *tags, const char *message, ...);

引数:

- buffer: バッファへのポインタ、NULL の場合、メッセージは WeeChat バッファに表示

- date: メッセージの日付 (0 は現在の日付/時間を意味する)

- date_usec: microseconds of date (between 0 and 999999)

- tags: タグのコンマ区切りリスト (タグを指定しない場合は NULL)

- message: 表示するメッセージ

WeeChat で共通に使われるタグのリストは WeeChat ユーザーズガイド / 行のタグ ↗を参照してください

C 言語での使用例:

    struct timeval tv_now;

    gettimeofday (&tv_now, NULL);
    weechat_printf_datetime_tags (NULL, tv_now.tv_sec - 120, tv_now.tv_usec,
                                  "notify_message",
                                  "Message 2 minutes ago, with a tag 'notify_message'");

スクリプト (Python) での使用例:

    # プロトタイプ
    def prnt_datetime_tags(buffer: str, date: int, date_usec: int, tags: str, message: str) -> int: ...

    # 例
    now = time.time()
    time_sec = int(now)
    time_usec = int((now * 1000000) % 1000000)
    weechat.prnt_datetime_tags("", time_sec - 120, time_usec, "notify_message",
                               "Message 2 minutes ago, with a tag 'notify_message'")

注記 | この関数をスクリプトの中で実行するには "print_datetime_tags" (Python の場合は "prnt_datetime_tags") と書きます。

#### printf_y

自由内容のバッファのある行にメッセージを表示

プロトタイプ:

    void weechat_printf_y (struct t_gui_buffer *buffer, int y, const char *message, ...);

This function is a shortcut for function printf_y_datetime_tags.
These two calls give exactly same result:

    weechat_printf_y (buffer, 0, "message");
    weechat_printf_y_datetime_tags (buffer, 0, 0, 0, NULL, "message");

引数:

- buffer: バッファへのポインタ

- y: 行番号 (1 行目は 0); 負数の場合は表示された最後の行の後に行を追加する: y の絶対値で最後の行の後に追加する行数を指定 (例えば -1 は最後の行のすぐ後、-2 は 最後の行の 2 行後) (WeeChat バージョン 1.0 以上で利用可)

- message: 表示するメッセージ

C 言語での使用例:

    weechat_printf_y (buffer, 2, "My message on third line");

スクリプト (Python) での使用例:

    # プロトタイプ
    def prnt_y(buffer: str, y: int, message: str) -> int: ...

    # 例
    weechat.prnt_y("", 2, "My message on third line")

注記 | この関数をスクリプトの中で実行するには "print_y" (Python の場合は "prnt_y") と書きます。

#### printf_y_date_tags

WeeChat ≥ 3.5.

Display a message on a line of a buffer with free content, using a custom date and tags.

プロトタイプ:

    void weechat_printf_y_date_tags (struct t_gui_buffer *buffer, int y, time_t date,
                                     const char *tags, const char *message, ...);

This function is a shortcut for function printf_y_datetime_tags.
These two calls give exactly same result:

    weechat_printf_y_date_tags (buffer, 0, 0, NULL, "message");
    weechat_printf_y_datetime_tags (buffer, 0, 0, 0, NULL, "message");

引数:

- buffer: バッファへのポインタ

- y: 行番号 (1 行目は 0); 負数の場合は表示された最後の行の後に行を追加する: y の絶対値で最後の行の後に追加する行数を指定 (例えば -1 は最後の行のすぐ後、-2 は 最後の行の 2 行後)

- date: メッセージの日付 (0 は現在の日付/時間を意味する)

- tags: タグのコンマ区切りリスト (タグを指定しない場合は NULL)

- message: 表示するメッセージ

C 言語での使用例:

    weechat_printf_y_date_tags (buffer, 2, 0, "my_tag", "My message on third line with a tag");

スクリプト (Python) での使用例:

    # プロトタイプ
    def prnt_y_date_tags(buffer: str, y: int, date: int, tags: str, message: str) -> int: ...

    # 例
    weechat.prnt_y_date_tags("", 2, 0, "my_tag", "My message on third line with a tag")

注記 | この関数をスクリプトの中で実行するには "print_y_date_tags" (Python の場合は "prnt_y_date_tags") と書きます。

#### printf_y_datetime_tags

WeeChat ≥ 4.2.0.

Display a message on a line of a buffer with free content, using a custom date/time (with microseconds) and tags.

プロトタイプ:

    void weechat_printf_y_datetime_tags (struct t_gui_buffer *buffer, int y, time_t date,
                                         int date_usec, const char *tags, const char *message, ...);

引数:

- buffer: バッファへのポインタ

- y: 行番号 (1 行目は 0); 負数の場合は表示された最後の行の後に行を追加する: y の絶対値で最後の行の後に追加する行数を指定 (例えば -1 は最後の行のすぐ後、-2 は 最後の行の 2 行後)

- date: メッセージの日付 (0 は現在の日付/時間を意味する)

- date_usec: microseconds of date (between 0 and 999999)

- tags: タグのコンマ区切りリスト (タグを指定しない場合は NULL)

- message: 表示するメッセージ

C 言語での使用例:

    weechat_printf_y_datetime_tags (buffer, 2, 0, 0, "my_tag", "My message on third line with a tag");

スクリプト (Python) での使用例:

    # プロトタイプ
    def prnt_y_datetime_tags(buffer: str, y: int, date: int, date_usec: int, tags: str, message: str) -> int: ...

    # 例
    weechat.prnt_y_datetime_tags("", 2, 0, 0, "my_tag", "My message on third line with a tag")

注記 | この関数をスクリプトの中で実行するには "print_y_datetime_tags" (Python の場合は "prnt_y_datetime_tags") と書きます。

#### log_printf

WeeChat ログファイル (weechat.log) にメッセージを書き込む。

プロトタイプ:

    void weechat_log_printf (const char *message, ...);

引数:

- message: 書き込むメッセージ

C 言語での使用例:

    weechat_log_printf ("My message in log file");

スクリプト (Python) での使用例:

    # プロトタイプ
    def log_print(message: str) -> int: ...

    # 例
    weechat.log_print("My message in log file")

注記 | この関数をスクリプトの中で実行するには "log_print" と書きます。

### 3.14. フック

#### フックの優先度

WeeChat バージョン 0.3.4 以上で利用可。

一部のフックに対して優先度を設定することができます。フックリストは優先度の高い順にフックが並べられ、高い優先度を持つフックはそれよりも低い優先度を持つフックが実行される前に実行されます。これは実行順序が重要となる修飾子で便利です。

優先度が指定できる引数に優先度を設定するには、必ず以下の構文を使ってください: `nnn|name` ここで `nnn` は優先度を示すゼロおよび正の整数で `name` は引数の名前です (優先度は自動的に文字列から削除され、フックの名前になります)。
Only a single priority per hook is allowed.

デフォルトの優先度は 1000 です。

C examples:

    /* hook modifier with priority = 2000 */
    /* high priority: called before other modifier callbacks */
    weechat_hook_modifier ("2000|input_text_display", &modifier_cb, NULL, NULL);

    /* hook two signals with priority = 3000 */
    /* high priority: called before other signal callbacks */
    weechat_hook_signal ("3000|quit;upgrade", &signal_cb, NULL, NULL);

    /* hook lines printed in formatted buffers with priority = 500 */
    /* low priority: called after other line callbacks */
    weechat_hook_line ("500|formatted", "*", NULL, &line_cb, NULL, NULL);

以下のフック型に対して優先度を設定できます:

- command

- completion

- command_run

- line

- signal

- hsignal

- config

- modifier

- info

- info_hashtable

- infolist

- hdata

- focus

#### hook_command

WeeChat バージョン 1.5 と 1.7 で更新。

コマンドをフックする。

プロトタイプ:

    struct t_hook *weechat_hook_command (const char *command,
                                         const char *description,
                                         const char *args,
                                         const char *args_description,
                                         const char *completion,
                                         int (*callback)(const void *pointer,
                                                         void *data,
                                                         struct t_gui_buffer *buffer,
                                                         int argc,
                                                         char **argv,
                                                         char **argv_eol),
                                         const void *callback_pointer,
                                         void *callback_data);

引数:

- command: コマンド名 (a priority is allowed before the command, see note about priority)

- description: コマンドの説明 (`/help command` で表示されます)

- args: コマンドの引数 (`/help command` で表示されます)

- args_description: 引数の説明 (`/help command` で表示されます)

- completion: コマンドに対する補完候補テンプレート (書式は以下を参照してください)

- callback: コマンドが使用された際に呼び出すコールバック関数、引数と戻り値:

  - const void *pointer: ポインタ

  - void *data: ポインタ

  - struct t_gui_buffer *buffer: コマンドを実行するバッファ

  - int argc: コマンドに渡す引数の個数

  - char **argv: コマンドに渡す引数

  - char **argv_eol: コマンドに渡す引数 (最初の引数から各引数までを収めた文字列)

  - 戻り値:

    - WEECHAT_RC_OK

    - WEECHAT_RC_ERROR

- callback_pointer: WeeChat が callback コールバックを呼び出す際にコールバックに渡すポインタ

- callback_data: WeeChat が callback コールバックを呼び出す際にコールバックに渡すポインタ; このポインタが NULL でない場合、このポインタは malloc (または類似の関数) によって割り当てられたものでなければいけません。さらに、このポインタはここで作成したフックが削除された時点で自動的に開放されます

上の completion テンプレートは各引数に関する補完候補の空白区切りリストです。1 つの引数に対して複数の補完候補を設定するには補完候補同士を `|` で区切ってください。1 つのコマンドに対して複数のテンプレートを設定するにはテンプレート同士を `||` で区切ってください。

補完候補テンプレートには以下の書式を使えます:

- %(name): name という補完候補テンプレート

- %(name:arguments): arguments という引数をつけた name という補完候補テンプレートがコールバックに送信されます (WeeChat バージョン 1.7 以上)

- 任意の文字列: 補完候補としてそのまま使われる文字列

例えば `list || add %(filters_names) || del %(filters_names)|-all` という補完候補テンプレートはコマンド引数として以下の値を補完します:

- 第 1 引数: `list`、`add`、`del`

- 第 2 引数、第 1 引数に依存:

  - `list`: 第 2 引数なし

  - `add`: フィルタ名

  - `del`: フィルタ名および `-all`

デフォルトの補完候補コードは:

Plugin | Name | Description
--- | --- | ---
alias | alias | list of aliases
alias | alias_value | value of alias
buflist | buflist_items | buflist bar items
buflist | buflist_items_used | buflist bar items used (according to option buflist.look.use_items)
exec | exec_commands_ids | ids (numbers and names) of executed commands
fset | fset_options | configuration files, sections, options and words of options
guile | guile_script | list of scripts
irc | irc_channel | current IRC channel
irc | irc_channel_nicks_hosts | nicks and hostnames of current IRC channel
irc | irc_channel_topic | topic of current IRC channel
irc | irc_channels | channels on all IRC servers
irc | irc_channels_autojoin | channels automatically joined on the current server (option "autojoin")
irc | irc_ignores_numbers | numbers for defined ignores
irc | irc_modelist_masks | modelist masks of current IRC channel; required argument: modelist mode
irc | irc_modelist_numbers | modelist numbers of current IRC channel; required argument: modelist mode
irc | irc_msg_kick | default kick message
irc | irc_msg_part | default part message for IRC channel
irc | irc_notify_nicks | nicks in notify list
irc | irc_privates | privates on all IRC servers
irc | irc_raw_filters | filters for irc raw buffer
irc | irc_server | current IRC server
irc | irc_server_channels | channels on current IRC server
irc | irc_server_nick | nick on current IRC server
irc | irc_server_nicks | nicks on all channels of current IRC server
irc | irc_server_prefix_modes_filter | arguments to filter by prefix mode (for example: "-o", "-h", "-v", "-*")
irc | irc_server_privates | privates on current IRC server
irc | irc_servers | IRC servers (internal names)
irc | nick | nicks of current IRC channel
lua | lua_script | list of scripts
perl | perl_script | list of scripts
php | php_script | list of scripts
python | python_script | list of scripts
relay | relay_free_port | first free port for relay plugin
relay | relay_protocol_name | all possible protocol.name for relay plugin
relay | relay_relays | protocol.name of current relays for relay plugin
relay | relay_remotes | relay remotes
ruby | ruby_script | list of scripts
script | script_extensions | list of script extensions
script | script_files | files in script directories
script | script_languages | list of script languages
script | script_scripts | list of scripts in repository
script | script_scripts_installed | list of scripts installed (from repository)
script | script_tags | tags of scripts in repository
spell | spell_dicts | list of installed dictionaries
spell | spell_langs | list of all languages supported
tcl | tcl_script | list of scripts
trigger | trigger_add_arguments | arguments for command that adds a trigger: trigger name, hooks, hook arguments, hook conditions, hook regex, hook command, hook return code, post actions
trigger | trigger_hook_arguments | default arguments for a hook
trigger | trigger_hook_command | default command for a hook
trigger | trigger_hook_conditions | default conditions for a hook
trigger | trigger_hook_rc | default return codes for hook callback
trigger | trigger_hook_regex | default regular expression for a hook
trigger | trigger_hooks | hooks for triggers
trigger | trigger_hooks_filter | hooks for triggers (for filter in monitor buffer)
trigger | trigger_names | triggers
trigger | trigger_names_default | default triggers
trigger | trigger_names_disabled | disabled triggers
trigger | trigger_names_enabled | enabled triggers
trigger | trigger_option_value | value of a trigger option
trigger | trigger_options | options for triggers
trigger | trigger_post_action | trigger post actions
weechat | bars_items | names of bar items
weechat | bars_names | names of bars
weechat | bars_options | options for bars
weechat | buffer_local_variable_value | value of a buffer local variable
weechat | buffer_local_variables | buffer local variables
weechat | buffer_properties_get | properties that can be read on a buffer
weechat | buffer_properties_set | properties that can be set on a buffer
weechat | buffer_properties_setauto | properties that can be automatically set on a buffer
weechat | buffers_names | names of buffers
weechat | buffers_numbers | numbers of buffers
weechat | buffers_plugins_names | names of buffers (including plugins names)
weechat | colors | color names
weechat | commands | commands (weechat and plugins); optional argument: prefix to add before the commands
weechat | config_files | configuration files
weechat | config_option_values | values for a configuration option
weechat | config_options | configuration options
weechat | cursor_areas | areas ("chat" or bar name) for free cursor movement
weechat | custom_bar_item_add_arguments | arguments for command that adds a custom bar item: item name, conditions, content
weechat | custom_bar_item_conditions | conditions for custom bar item
weechat | custom_bar_item_contents | contents for custom bar item
weechat | custom_bar_items_names | names of custom bar items
weechat | env_value | value of an environment variable
weechat | env_vars | environment variables
weechat | eval_variables | variables that can be used in /eval command
weechat | filename | filename; optional argument: default path (evaluated, see /help eval)
weechat | filters_names | names of filters
weechat | filters_names_disabled | names of disabled filters
weechat | filters_names_enabled | names of enabled filters
weechat | hook_types | hook types
weechat | infolists | names of infolists hooked
weechat | infos | names of infos hooked
weechat | keys_codes | key codes
weechat | keys_codes_for_reset | key codes that can be reset (keys added, redefined or removed)
weechat | keys_contexts | key contexts
weechat | layouts_names | names of layouts
weechat | nicks | nicks in nicklist of current buffer
weechat | palette_colors | palette colors
weechat | plugins_commands | commands defined by plugins; optional argument: prefix to add before the commands
weechat | plugins_installed | names of plugins installed
weechat | plugins_names | names of plugins
weechat | proxies_names | names of proxies
weechat | proxies_options | options for proxies
weechat | secured_data | names of secured data (file sec.conf, section data)
weechat | weechat_commands | weechat commands; optional argument: prefix to add before the commands
weechat | windows_numbers | numbers of windows
xfer | nick | nicks of DCC chat

特殊コード:

- `%%command`: コマンド command と同じ補完候補テンプレートを使用

- `%-`: 補完の中止

- `%*`: 最後の補完候補を繰り返す

戻り値:

- 新しいフックへのポインタ、エラーが起きた場合は NULL

C 言語での使用例:

    int
    my_command_cb (const void *pointer, void *data, struct t_gui_buffer *buffer,
                   int argc, char **argv, char **argv_eol)
    {
        /* ... */
        return WEECHAT_RC_OK;
    }

    /* this example is inspired by command /filter */
    struct t_hook *my_command_hook =
        weechat_hook_command ("myfilter",
                              "description of myfilter",
                              "[list] | [enable|disable|toggle [name]] | "
                              "[add name plugin.buffer tags regex] | "
                              "[del name|-all]",
                              "description of arguments...",
                              "list"
                              " || enable %(filters_names)"
                              " || disable %(filters_names)"
                              " || toggle %(filters_names)"
                              " || add %(filters_names) %(buffers_plugins_names)|*"
                              " || del %(filters_names)|-all",
                              &my_command_cb, NULL, NULL);

例えば、コマンドが `/command abc def ghi` のように実行された場合、argv と argv_eol は以下のようになります:

- argv:

  - argv[0] == "/command"

  - argv[1] == "abc"

  - argv[2] == "def"

  - argv[3] == "ghi"

- argv_eol:

  - argv_eol[0] == "/command abc def ghi"

  - argv_eol[1] == "abc def ghi"

  - argv_eol[2] == "def ghi"

  - argv_eol[3] == "ghi"

スクリプトでは、args は "abc def ghi" のようになります。

スクリプト (Python) での使用例:

    # プロトタイプ
    def hook_command(command: str, description: str, args: str, args_description: str,
                     completion: str, callback: str, callback_data: str) -> str: ...

    # 例
    def my_command_cb(data: str, buffer: str, args: str) -> int:
        # ...
        return weechat.WEECHAT_RC_OK

    hook = weechat.hook_command("myfilter", "description of myfilter",
        "[list] | [enable|disable|toggle [name]] | [add name plugin.buffer tags regex] | [del name|-all]",
        "description of arguments...",
        "list"
        " || enable %(filters_names)"
        " || disable %(filters_names)"
        " || toggle %(filters_names)"
        " || add %(filters_names) %(buffers_plugins_names)|*"
        " || del %(filters_names)|-all",
        "my_command_cb", "")

#### hook_completion

WeeChat バージョン 1.5 と 1.7 で更新。

補完をフック。

プロトタイプ:

    struct t_hook *weechat_hook_completion (const char *completion_item,
                                            const char *description,
                                            int (*callback)(const void *pointer,
                                                            void *data,
                                                            const char *completion_item,
                                                            struct t_gui_buffer *buffer,
                                                            struct t_gui_completion *completion),
                                            const void *callback_pointer,
                                            void *callback_data);

引数:

- completion_item: 補完候補テンプレートの名前、これ以降コマンドフックの completion 引数で %(name) という補完候補テンプレートを使えます (WeeChat バージョン 1.7 以上の場合 %(name:arguments) も使えます) (a priority is allowed before the completion item, see note about priority)

- description: 補完候補テンプレートの説明

- callback: 補完候補テンプレート (ユーザはこの関数を使って何かを補完します) が使われた場合に呼び出すコールバック関数、引数と戻り値:

  - const void *pointer: ポインタ

  - void *data: ポインタ

  - const char *completion_item: 補完候補テンプレートの名前 (WeeChat バージョン 1.7 以上の場合、次の書式で引数を含めることも可能です: name:arguments)

  - struct t_gui_buffer *buffer: 補完が行われたバッファ

  - struct t_gui_completion *completion: 補完に際して単語を追加するために使われる構造体 (completion_list_add を参照)

  - 戻り値:

    - WEECHAT_RC_OK

    - WEECHAT_RC_ERROR

- callback_pointer: WeeChat が callback コールバックを呼び出す際にコールバックに渡すポインタ

- callback_data: WeeChat が callback コールバックを呼び出す際にコールバックに渡すポインタ; このポインタが NULL でない場合、このポインタは malloc (または類似の関数) によって割り当てられたものでなければいけません。さらに、このポインタはここで作成したフックが削除された時点で自動的に開放されます

注記 | 補完名はグローバルです (WeeChat とプラグインで共有されます)。このため、"plugin_xxx" (ここで "xxx" は要素の名前) などの一意的なプレフィックスをつけた名前を使うことをおすすめします。

重要 | The callback must only call completion functions like completion_list_add and must NOT update the command line. `Tab` が押された時にコマンドラインを更新するためには、関数 hook_command_run を使ってコマンド `/input complete_next` をフックしてください (コールバックがコマンドラインを更新する場合は必ず WEECHAT_RC_OK_EAT を返してください。そうすれば WeeChat は補完を行いません)。

戻り値:

- 新しいフックへのポインタ、エラーが起きた場合は NULL

C 言語での使用例:

    int
    my_completion_cb (const void *pointer, void *data, const char *completion_item,
                      struct t_gui_buffer *buffer,
                      struct t_gui_completion *completion)
    {
        weechat_completion_list_add (completion, "word1", 0, WEECHAT_LIST_POS_SORT);
        weechat_completion_list_add (completion, "test_word2", 0, WEECHAT_LIST_POS_SORT);
        return WEECHAT_RC_OK;
    }

    struct t_hook *my_completion_hook = weechat_hook_completion ("plugin_item",
                                                                 "my custom completion!",
                                                                 &my_completion_cb, NULL, NULL);

スクリプト (Python) での使用例:

    # プロトタイプ
    def hook_completion(completion_item: str, description: str, callback: str, callback_data: str) -> str: ...

    # 例
    def my_completion_cb(data: str, completion_item: str, buffer: str, completion: str) -> int:
        weechat.completion_list_add(completion, "word1", 0, weechat.WEECHAT_LIST_POS_SORT)
        weechat.completion_list_add(completion, "test_word2", 0, weechat.WEECHAT_LIST_POS_SORT)
        return weechat.WEECHAT_RC_OK

    hook = weechat.hook_completion("plugin_item", "my custom completion!",
                                   "my_completion_cb", "")

#### hook_completion_get_string

WeeChat バージョン 0.3.4 以上で利用可。

Deprecated since WeeChat 2.9 (still there for compatibility).
This function has been replaced by completion_get_string.

#### hook_completion_list_add

Deprecated since WeeChat 2.9 (still there for compatibility).
This function has been replaced by completion_list_add.

#### hook_command_run

WeeChat バージョン 1.5 で更新。

WeeChat がコマンドを実行する際にこれをフック。

プロトタイプ:

    struct t_hook *weechat_hook_command_run (const char *command,
                                             int (*callback)(const void *pointer,
                                                             void *data,
                                                             struct t_gui_buffer *buffer,
                                                             const char *command),
                                             const void *callback_pointer,
                                             void *callback_data);

引数:

- command: フックするコマンド (ワイルドカード `*` を使うことができます) (a priority is allowed before the command, see note about priority)

- callback: コマンドが実行される際に呼び出すコールバック関数、引数と戻り値:

  - const void *pointer: ポインタ

  - void *data: ポインタ

  - struct t_gui_buffer *buffer: コマンドを実行するバッファ

  - const char *command: 実行するコマンド、引数付き

  - 戻り値:

    - WEECHAT_RC_OK

    - WEECHAT_RC_OK_EAT: コールバックの後にコマンドを実行しない

    - WEECHAT_RC_ERROR

- callback_pointer: WeeChat が callback コールバックを呼び出す際にコールバックに渡すポインタ

- callback_data: WeeChat が callback コールバックを呼び出す際にコールバックに渡すポインタ; このポインタが NULL でない場合、このポインタは malloc (または類似の関数) によって割り当てられたものでなければいけません。さらに、このポインタはここで作成したフックが削除された時点で自動的に開放されます

戻り値:

- 新しいフックへのポインタ、エラーが起きた場合は NULL

C 言語での使用例:

    int
    my_command_run_cb (const void *pointer, void *data,
                       struct t_gui_buffer *buffer, const char *command)
    {
        weechat_printf (NULL, "I'm eating the completion!");
        return WEECHAT_RC_OK_EAT;
    }

    struct t_hook *my_command_run_hook =
        weechat_hook_command_run ("/input complete*",
                                  &my_command_run_cb, NULL, NULL);

スクリプト (Python) での使用例:

    # プロトタイプ
    def hook_command_run(command: str, callback: str, callback_data: str) -> str: ...

    # 例
    def my_command_run_cb(data: str, buffer: str, command: str) -> int:
        weechat.prnt("", "I'm eating the completion!")
        return weechat.WEECHAT_RC_OK_EAT

    hook = weechat.hook_command_run("/input complete*", "my_command_run_cb", "")

#### hook_timer

WeeChat バージョン 1.5 で更新。

タイマをフックする。

プロトタイプ:

    struct t_hook *weechat_hook_timer (long interval,
                                       int align_second,
                                       int max_calls,
                                       int (*callback)(const void *pointer,
                                                       void *data,
                                                       int remaining_calls),
                                       const void *callback_pointer,
                                       void *callback_data);

引数:

- interval: 2 つの呼び出し間隔 (ミリ秒、1000 = 1 秒)

- align_second: 秒の調整。例えば、現在時刻が 09:00、 interval = 60000 (60 秒)、align_second = 60 の場合、毎分 0 秒時にタイマを呼び出す

- max_calls: タイマを呼び出す回数 (0 の場合、タイマを無限に呼び出す)

- callback: 時間が来たら呼び出すコールバック関数、引数と戻り値:

  - const void *pointer: ポインタ

  - void *data: ポインタ

  - int remaining_calls: 呼び出し残り回数 (タイマを無限に呼び出す場合は -1)

  - 戻り値:

    - WEECHAT_RC_OK

    - WEECHAT_RC_ERROR

- callback_pointer: WeeChat が callback コールバックを呼び出す際にコールバックに渡すポインタ

- callback_data: WeeChat が callback コールバックを呼び出す際にコールバックに渡すポインタ; このポインタが NULL でない場合、このポインタは malloc (または類似の関数) によって割り当てられたものでなければいけません。さらに、このポインタはここで作成したフックが削除された時点で自動的に開放されます

戻り値:

- 新しいフックへのポインタ、エラーが起きた場合は NULL

C 言語での使用例:

    int
    my_timer_cb (const void *pointer, void *data, int remaining_calls)
    {
        /* ... */
        return WEECHAT_RC_OK;
    }

    /* timer called each 20 seconds */
    struct t_hook *my_timer_hook =
        weechat_hook_timer (20 * 1000, 0, 0, &my_timer_cb, NULL, NULL);

スクリプト (Python) での使用例:

    # プロトタイプ
    def hook_timer(interval: int, align_second: int, max_calls: int, callback: str, callback_data: str) -> str: ...

    # 例
    def my_timer_cb(data: str, remaining_calls: int) -> int:
        # ...
        return weechat.WEECHAT_RC_OK

    # timer called each 20 seconds
    hook = weechat.hook_timer(20 * 1000, 0, 0, "my_timer_cb", "")

#### hook_fd

WeeChat バージョン 1.3、1.5、2.0 で更新。

ファイルディスクリプタ (ファイルやソケット) をフック。

プロトタイプ:

    struct t_hook *weechat_hook_fd (int fd,
                                    int flag_read,
                                    int flag_write,
                                    int flag_exception,
                                    int (*callback)(const void *pointer,
                                                    void *data,
                                                    int fd),
                                    const void *callback_pointer,
                                    void *callback_data);

引数:

- fd: ファイルディスクリプタ

- flag_read: 1 = ロードイベントをキャッチ、0 = 無視

- flag_write: 1 = 書き込みイベントをキャッチ、0 = 無視

- flag_exception: 1 = 例外イベントをキャッチ、0 = 無視 (WeeChat バージョン 1.3 以上の場合: この引数は無視され、使われません)

- callback: ファイル (またはソケット) に対してキャッチしたいイベントが発生した場合に実行するコールバック関数、引数と戻り値:

  - const void *pointer: ポインタ

  - void *data: ポインタ

  - int fd: ファイルディスクリプタ

  - 戻り値:

    - WEECHAT_RC_OK

    - WEECHAT_RC_ERROR

- callback_pointer: WeeChat が callback コールバックを呼び出す際にコールバックに渡すポインタ

- callback_data: WeeChat が callback コールバックを呼び出す際にコールバックに渡すポインタ; このポインタが NULL でない場合、このポインタは malloc (または類似の関数) によって割り当てられたものでなければいけません。さらに、このポインタはここで作成したフックが削除された時点で自動的に開放されます

戻り値:

- 新しいフックへのポインタ、エラーが起きた場合は NULL

重要 | スクリプトにおけるコールバック引数 fd は WeeChat バージョン 2.0 以上では整数、バージョン 1.9 以下では文字列です。 すべてのバージョンで互換性を保つには、使用前にコールバック引数 fd を整数へ変換することを推奨します (Python の場合 `int(fd)` のように変換してください)。

C 言語での使用例:

    int
    my_fd_cb (const void *pointer, void *data, int fd)
    {
        /* ... */
        return WEECHAT_RC_OK;
    }

    int sock = socket (AF_INET, SOCK_STREAM, 0);
    /* set socket options */
    /* ... */
    struct t_hook *my_fd_hook = weechat_hook_fd (sock, 1, 0, 0, &my_fd_cb, NULL, NULL);

スクリプト (Python) での使用例:

    # プロトタイプ
    def hook_fd(fd: int, flag_read: int, flag_write: int, flag_exception: int, callback: str, callback_data: str) -> str: ...

    # 例
    def my_fd_cb(data: str, fd: int) -> int:
        # ...
        return weechat.WEECHAT_RC_OK

    sock = ...
    hook = weechat.hook_fd(sock, 1, 0, 0, "my_fd_cb", "")

#### hook_process

WeeChat バージョン 1.5 で更新。

プロセスをフックして (フォークして実行)、出力を受け取る。

注記 | WeeChat バージョン 0.3.9.2 以上の場合、コマンドを実行するためにシェルを使わないようになりました。WeeChat が自動的にコマンドと引数を分割します (シェルがやっているように)。 分割 (引用符に基づくコマンド分割) に失敗する場合、またはシェルを使いたい場合は、ハッシュテーブル options に引数を入れて hook_process_hashtable 関数を使ってください (WeeChat バージョン 0.4.0 以上で利用可)。

プロトタイプ:

    struct t_hook *weechat_hook_process (const char *command,
                                         int timeout,
                                         int (*callback)(const void *pointer,
                                                         void *data,
                                                         const char *command,
                                                         int return_code,
                                                         const char *out,
                                                         const char *err),
                                         const void *callback_pointer,
                                         void *callback_data);

引数:

- command: 子プロセスで実行するコマンド、URL (WeeChat バージョン 0.3.7 以上で利用可) または関数 (WeeChat バージョン 1.5 以上で利用可) (下記参照)

- timeout: コマンドのタイムアウト (ミリ秒): このタイムアウトを過ぎたら、子プロセスを kill します (タイムアウトさせない場合は 0)

- callback: 子プロセスからのデータが利用可能になるか、子プロセスが終了したら呼び出すコールバック関数、引数と戻り値:

  - const void *pointer: ポインタ

  - void *data: ポインタ

  - const char *command: 子プロセスが実行するコマンド

  - int return_code: リターンコード:

    - ≥ 0: コマンドを実行した子プロセスのまたは URL に対するリターンコード。URL の場合に取り得る値は:

      - 0: 転送に成功

      - 1: 無効な URL

      - 2: 転送エラー

      - 3: メモリ不足

      - 4: ファイルに関するエラー

    - < 0:

      - WEECHAT_HOOK_PROCESS_RUNNING (-1): データは利用可能だが子プロセスは終了していない

      - WEECHAT_HOOK_PROCESS_ERROR (-2): コマンドの起動中にエラー

      - WEECHAT_HOOK_PROCESS_CHILD (-3): 子プロセスからコールバックが呼び出された (used only in C API, not scripting API)

  - out: コマンドの標準出力 (stdout)

  - err: コマンドの標準エラー出力 (stderr)

  - 戻り値:

    - WEECHAT_RC_OK

    - WEECHAT_RC_ERROR

    - 子プロセスのリターンコード (command に "func:" を指定して関数を実行した場合)

- callback_pointer: WeeChat が callback コールバックを呼び出す際にコールバックに渡すポインタ

- callback_data: WeeChat が callback コールバックを呼び出す際にコールバックに渡すポインタ; このポインタが NULL でない場合、このポインタは malloc (または類似の関数) によって割り当てられたものでなければいけません。さらに、このポインタはここで作成したフックが削除された時点で自動的に開放されます

戻り値:

- 新しいフックへのポインタ、エラーが起きた場合は NULL

コマンドが終了するか、タイムアウトを過ぎた場合、WeeChat は自動的にフックを解除します (プロセスが実行中であればプロセスを kill します)。

コマンドを "url:https://www.example.com" の書式に従う URL にすることで、URL の内容がダウンロードされます (WeeChat バージョン 0.3.7 以上で利用可)。hook_process_hashtable 関数を使えば URL に対してオプションを与えることもできます。

command には関数名を指定することも可能です。"name" という関数を実行するには "func:name" のように指定します (WeeChat バージョン 1.5 以上で利用可)。ここで指定した関数 "name" は単独の引数 (data) を受け取り、文字列を返すものでなければいけません。関数から返された文字列が callback コールバックに送られます。
C API の場合、callback コールバックが return_code リターンコードに WEECHAT_HOOK_PROCESS_CHILD が設定された状態で呼び出されます。すなわち (フォークの後に) 子プロセスが呼び出すのは関数 "name" ではなく callback コールバックです。
スクリプト API の場合、子プロセスが呼び出すのは関数 "name" であり、関数 "name" の戻り値 (文字列) が callback コールバックに送られます (関数の戻り値は外部コマンドを実行した場合の出力と同様に取り扱われます)。

ヒント | If you want to retrieve infos about WeeChat (like current stable version, latest git commit, etc.), you can use URLs on this page ↗.

注記 | コールバックにデータを送信するバッファのサイズは 64KB (バッファは 2 つあります: 標準出力用と、標準エラー出力用) です。子プロセスからの出力 (標準出力または標準エラー出力) が 64KB よりも大きくなった場合は、コールバックを 1 回以上呼び出します。

重要 | コールバックを 1 回より多く呼び出すことが皆無だとしても、コールバックを複数回呼び出しても安全なようにコードを書いてください: 必ず複数回送られたデータを連結し、データを使うのは戻り値が正またはゼロの時だけにしてください。

C 言語での使用例:

    /* 外部コマンドを実行する例 */
    int
    my_process_cb (const void *pointer, void *data, const char *command,
                   int return_code, const char *out, const char *err)
    {
        if (return_code == WEECHAT_HOOK_PROCESS_ERROR)
        {
            weechat_printf (NULL, "Error with command '%s'", command);
            return WEECHAT_RC_OK;
        }

        if (return_code >= 0)
        {
            weechat_printf (NULL, "return_code = %d", return_code);
        }

        if (out)
        {
            weechat_printf (NULL, "stdout: %s", out);
        }

        if (err)
        {
            weechat_printf (NULL, "stderr: %s", err);
        }

        return WEECHAT_RC_OK;
    }

    struct t_hook *my_process_hook = weechat_hook_process ("ls", 5000,
                                                           &my_process_cb, NULL, NULL);

    /* 子プロセスからコールバックを呼び出す例 */
    int
    my_process_func_cb (const void *pointer, void *data, const char *command,
                        int return_code, const char *out, const char *err)
    {
        if (return_code == WEECHAT_HOOK_PROCESS_CHILD)
        {
            /* 何かブロックを生じさせるようなことを実行... */
            /* ... */

            /* 親プロセスはこの標準出力の内容を "out" に設定して、コールバックを呼び出します */
            printf ("this is the result");

            /* このプロセスの戻り値 */
            return 0;
        }
        else
        {
            if (return_code == WEECHAT_HOOK_PROCESS_ERROR)
            {
                weechat_printf (NULL, "Error with command '%s'", command);
                return WEECHAT_RC_OK;
            }

            if (return_code >= 0)
            {
                weechat_printf (NULL, "return_code = %d", return_code);
            }

            if (out)
            {
                weechat_printf (NULL, "stdout: %s", out);
            }

            if (err)
            {
                weechat_printf (NULL, "stderr: %s", err);
            }

            return WEECHAT_RC_OK;
        }
    }

    struct t_hook *my_process_hook = weechat_hook_process ("func:get_status", 5000,
                                                           &my_process_func_cb, NULL, NULL);

スクリプト (Python) での使用例:

    # プロトタイプ
    def hook_process(command: str, timeout: int, callback: str, callback_data: str) -> str: ...

    # 外部コマンドを実行する例
    def my_process_cb(data: str, command: str, return_code: int, out: str, err: str) -> int:
        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("ls", 5000, "my_process_cb", "")

    # スクリプト関数を実行する例
    def get_status(data: str) -> str:
        # 何かブロックを生じさせるようなことを実行...
        # ...
        return "this is the result"

    def my_process_cb(data: str, command: str, return_code: int, out: str, err: str) -> int:
        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", "")

#### hook_process_hashtable

WeeChat バージョン 0.3.7 以上で利用可、バージョン 1.5 で更新。

ハッシュテーブルに収めたオプションを使いプロセスをフックする (フォークして実行)、出力を受け取る。

プロトタイプ:

    struct t_hook *weechat_hook_process_hashtable (const char *command,
                                                   struct t_hashtable *options,
                                                   int timeout,
                                                   int (*callback)(const void *pointer,
                                                                   void *data,
                                                                   const char *command,
                                                                   int return_code,
                                                                   const char *out,
                                                                   const char *err),
                                                   const void *callback_pointer,
                                                   void *callback_data);

引数は以下の追加引数を除いて hook_process 関数と同じです:

- options: 実行するコマンドのオプション; ハッシュテーブルは関数の中で複製されるため、この関数を呼び出した後にハッシュテーブルを安全に開放できます。

一般的なコマンド (最初に "url:" が付かないコマンド) では、以下のオプションを使うことができます:

オプション | Min WeeChat | 値 | デフォルト | 説明
--- | --- | --- | --- | ---
argN (N は 1 以上) | 0.4.0 | 任意の文字列 | 引数なし | コマンドの引数; このオプションを使って引数を渡さない場合、シェルと同じように引数を自動的に分割します (command 引数からコマンド引数をロードします)
stdin | 0.4.3 | (非使用) | 標準出力を使用しない | データを書き込むためのパイプを子プロセスの標準入力 (stdin) に作成します (関数 hook_set を参照)
buffer_flush | 1.0 | バイト数 | 65536 | 標準出力および標準エラー出力をフラッシュ (出力をコールバックヘ送信) するバイト数の最小値。取りうる値の範囲は 1 から 65536 までです。1 の場合、出力をすぐにコールバックへ送信します。
detached | 1.0 | (非使用) | detached モードで実行しない | detached モードでプロセスを実行: 標準出力と標準エラー出力を /dev/null にリダイレクトする

For command "url:…​", see available options in function hook_url.

戻り値:

- 新しいフックへのポインタ、エラーが起きた場合は NULL

C 言語での使用例:

    int
    my_process_cb (const void *pointer, void *data, const char *command,
                   int return_code, const char *out, const char *err)
    {
        if (return_code == WEECHAT_HOOK_PROCESS_ERROR)
        {
            weechat_printf (NULL, "Error with command '%s'", command);
            return WEECHAT_RC_OK;
        }

        if (return_code >= 0)
        {
            weechat_printf (NULL, "return_code = %d", return_code);
        }

        if (out)
        {
            weechat_printf (NULL, "stdout: %s", out);
        }

        if (err)
        {
            weechat_printf (NULL, "stderr: %s", err);
        }

        return WEECHAT_RC_OK;
    }

    /* 例 1: URL をダウンロード */
    struct t_hashtable *options_url1 = weechat_hashtable_new (8,
                                                              WEECHAT_HASHTABLE_STRING,
                                                              WEECHAT_HASHTABLE_STRING,
                                                              NULL,
                                                              NULL);
    if (options_url1)
    {
        weechat_hashtable_set (options_url1, "file_out", "/tmp/weechat.org.html");
        struct t_hook *my_process_hook = weechat_hook_process_hashtable ("url:https://weechat.org/",
                                                                         options_url1,
                                                                         20000,
                                                                         &my_process_cb, NULL, NULL);
        weechat_hashtable_free (options_url1);
    }

    /* 例 2: 任意の HTTP ヘッダを付けて URL を開く */
    struct t_hashtable *options_url2 = weechat_hashtable_new (8,
                                                              WEECHAT_HASHTABLE_STRING,
                                                              WEECHAT_HASHTABLE_STRING,
                                                              NULL,
                                                              NULL);
    if (options_url2)
    {
        weechat_hashtable_set (options_url2, "httpheader",
                               "Header1: value1\n"
                               "Header2: value2");
        struct t_hook *my_process_hook = weechat_hook_process_hashtable ("url:http://localhost:8080/",
                                                                         options_url2,
                                                                         20000,
                                                                         &my_process_cb, NULL, NULL);
        weechat_hashtable_free (options_url2);
    }

    /* 例 3: メッセージを渡して通知プログラムを実行 */
    struct t_hashtable *options_cmd1 = weechat_hashtable_new (8,
                                                              WEECHAT_HASHTABLE_STRING,
                                                              WEECHAT_HASHTABLE_STRING,
                                                              NULL,
                                                              NULL);
    if (options_cmd1)
    {
        weechat_hashtable_set (options_cmd1, "arg1", "-from");
        weechat_hashtable_set (options_cmd1, "arg2", nick);
        weechat_hashtable_set (options_cmd1, "arg3", "-msg");
        weechat_hashtable_set (options_cmd1, "arg4", message);  /* untrusted argument */
        struct t_hook *my_process_hook = weechat_hook_process_hashtable ("my-notify-command",
                                                                         options_cmd1,
                                                                         20000,
                                                                         &my_process_cb, NULL, NULL);
        weechat_hashtable_free (options_cmd1);
    }

    /* 例 4: コマンドを実行するためにシェルを呼び出す (必ず安全なコマンドを実行してください) */
    struct t_hashtable *options_cmd2 = weechat_hashtable_new (8,
                                                              WEECHAT_HASHTABLE_STRING,
                                                              WEECHAT_HASHTABLE_STRING,
                                                              NULL,
                                                              NULL);
    if (options_cmd2)
    {
        weechat_hashtable_set (options_cmd2, "arg1", "-c");
        weechat_hashtable_set (options_cmd2, "arg2", "ls -l /tmp | grep something");
        struct t_hook *my_process_hook = weechat_hook_process_hashtable ("sh",
                                                                         options_cmd2,
                                                                         20000,
                                                                         &my_process_cb, NULL, NULL);
        weechat_hashtable_free (options_cmd2);
    }

スクリプト (Python) での使用例:

    # プロトタイプ
    def hook_process_hashtable(command: str, options: Dict[str, str], timeout: int, callback: str, callback_data: str) -> str: ...

    # 例
    def my_process_cb(data: str, command: str, return_code: int, out: str, err: str) -> int:
        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

    # 例 1: URL をダウンロード
    hook1 = weechat.hook_process_hashtable("url:https://weechat.org/",
                                           {"file_out": "/tmp/weechat.org.html"},
                                           20000, "my_process_cb", "")

    # 例 2: 任意の HTTP ヘッダを付けて URL を開く
    options = {
        "httpheader": "\n".join([
            "Header1: value1",
            "Header2: value2",
        ]),
    }
    hook2 = weechat.hook_process_hashtable("url:http://localhost:8080/",
                                           options,
                                           20000, "my_process_cb", "")

    # 例 3: メッセージを渡して通知プログラムを実行
    hook3 = weechat.hook_process_hashtable("my-notify-command",
                                           {"arg1": "-from",
                                            "arg2": nick,
                                            "arg3": "-msg",
                                            "arg4": message},  # untrusted argument
                                           20000, "my_process_cb", "")

    # 例 4: コマンドを実行するためにシェルを呼び出す (必ず安全なコマンドを実行してください)
    hook4 = weechat.hook_process_hashtable("sh",
                                           {"arg1": "-c",
                                            "arg2": "ls -l /tmp | grep something"},
                                           20000, "my_process_cb", "")

#### hook_url

WeeChat ≥ 4.1.0.

URL transfer.

This function is similar to hook_process and hook_process_hashtable with command "url:…​" but it uses a thread instead of a new process, making it more lightweight and thus recommended for this usage.

プロトタイプ:

    struct t_hook *weechat_hook_url (const char *url,
                                     struct t_hashtable *options,
                                     int timeout,
                                     int (*callback)(const void *pointer,
                                                     void *data,
                                                     const char *url,
                                                     struct t_hashtable *options,
                                                     struct t_hashtable *output),
                                     const void *callback_pointer,
                                     void *callback_data);

引数:

- url: URL

- options: options for URL transfer (see below); ハッシュテーブルは関数の中で複製されるため、この関数を呼び出した後にハッシュテーブルを安全に開放できます。

- timeout: timeout for URL transfer (in milliseconds): after this timeout, the transfer is stopped (0 means no timeout)

- callback: function called when the transfer has ended, arguments and return value:

  - const void *pointer: pointer

  - void *data: pointer

  - const char *url: URL

  - struct t_hashtable *options: options

  - struct t_hashtable *output: result (keys and values are strings), which may contain the following keys:

    - response_code: HTTP response code

    - headers: HTTP headers in response

    - output: standard output (set only if file_out was not set in options)

    - error: error message (set only in case of error)

    - error_code: error code (integer, set only in case of error):

      - `1`: invalid URL

      - `2`: transfer error (Curl error)

      - `3`: not enough memory

      - `4`: file error

      - `5`: transfer stopped (hook removed during the transfer)

      - `6`: transfer timeout

      - `100`: thread creation error

    - error_code_pthread: return code of function pthread_create (integer, set only if error_code is `100`)

  - return value:

    - WEECHAT_RC_OK

    - WEECHAT_RC_ERROR

- callback_pointer: WeeChat が callback コールバックを呼び出す際にコールバックに渡すポインタ

- callback_data: WeeChat が callback コールバックを呼び出す際にコールバックに渡すポインタ; このポインタが NULL でない場合、このポインタは malloc (または類似の関数) によって割り当てられたものでなければいけません。さらに、このポインタはここで作成したフックが削除された時点で自動的に開放されます

The following Curl options are available (see `man curl_easy_setopt` for a description of each option):

Option | Type (1) | Constants (2)
--- | --- | ---
verbose | long |
header | long |
noprogress | long |
nosignal | long |
wildcardmatch | long |
failonerror | long |
keep_sending_on_error | long |
proxy | string |
proxyport | long |
port | long |
pre_proxy | string |
httpproxytunnel | long |
interface | string |
dns_cache_timeout | long |
proxytype | long | http, socks4, socks5, socks4a, socks5_hostname, http_1_0, https
buffersize | long |
tcp_nodelay | long |
localport | long |
localportrange | long |
address_scope | long |
noproxy | string |
socks5_gssapi_nec | long |
tcp_keepalive | long |
tcp_keepidle | long |
tcp_keepintvl | long |
unix_socket_path | string |
abstract_unix_socket | string |
path_as_is | long |
proxy_service_name | string |
service_name | string |
default_protocol | string |
tcp_fastopen | long |
socks5_auth | long |
haproxyprotocol | long |
doh_url | string |
protocols_str | string |
redir_protocols_str | string |
netrc | long | ignored, optional, required
userpwd | string |
proxyuserpwd | string |
httpauth | mask | none, basic, digest, ntlm, any, anysafe, digest_ie, only, negotiate, gssapi, bearer, aws_sigv4
proxyauth | mask | none, basic, digest, ntlm, any, anysafe, digest_ie, only, negotiate, gssapi, bearer, aws_sigv4
netrc_file | string |
username | string |
password | string |
proxyusername | string |
proxypassword | string |
tlsauth_type | mask | none, srp
tlsauth_username | string |
tlsauth_password | string |
sasl_authzid | string |
sasl_ir | long |
xoauth2_bearer | string |
login_options | string |
disallow_username_in_url | long |
autoreferer | long |
followlocation | long |
post | long |
postfields | string |
referer | string |
useragent | string |
httpheader | list |
cookie | string |
cookiefile | string |
postfieldsize | long |
maxredirs | long |
httpget | long |
cookiejar | string |
http_version | long | none, 1_0, 1_1, 2_0, 2, 2tls, 2_prior_knowledge, 3
cookiesession | long |
http200aliases | list |
unrestricted_auth | long |
postfieldsize_large | long long |
cookielist | string |
ignore_content_length | long |
accept_encoding | string |
transfer_encoding | long |
http_content_decoding | long |
http_transfer_decoding | long |
copypostfields | string |
postredir | mask | post_301, post_302
expect_100_timeout_ms | long |
headeropt | mask | unified, separate
proxyheader | list |
pipewait | long |
stream_weight | long |
request_target | string |
http09_allowed | long |
hsts | string |
hsts_ctrl | mask | enable, readonlyfile
mail_from | string |
mail_rcpt | list |
mail_auth | string |
mail_rcpt_allowfails | long |
tftp_blksize | long |
tftp_no_options | long |
ftpport | string |
quote | list |
postquote | list |
ftp_use_epsv | long |
prequote | list |
ftp_use_eprt | long |
ftp_create_missing_dirs | long |
ftpsslauth | long | default, ssl, tls
ftp_account | string |
ftp_skip_pasv_ip | long |
ftp_filemethod | long | multicwd, nocwd, singlecwd
ftp_alternative_to_user | string |
ftp_ssl_ccc | long | ccc_none, ccc_active, ccc_passive
dirlistonly | long |
append | long |
ftp_use_pret | long |
rtsp_request | long | options, describe, announce, setup, play, pause, teardown, get_parameter, set_parameter, record, receive
rtsp_session_id | string |
rtsp_stream_uri | string |
rtsp_transport | string |
rtsp_client_cseq | long |
rtsp_server_cseq | long |
aws_sigv4 | string |
crlf | long |
range | string |
resume_from | long |
customrequest | string |
nobody | long |
infilesize | long |
upload | long |
timecondition | long | none, ifmodsince, ifunmodsince, lastmod
timevalue | long |
transfertext | long |
filetime | long |
maxfilesize | long |
proxy_transfer_mode | long |
resume_from_large | long long |
infilesize_large | long long |
maxfilesize_large | long long |
timevalue_large | long long |
upload_buffersize | long |
mime_options | mask | formescape
timeout | long |
low_speed_limit | long |
low_speed_time | long |
fresh_connect | long |
forbid_reuse | long |
connecttimeout | long |
ipresolve | long | whatever, v4, v6
connect_only | long |
max_send_speed_large | long long |
max_recv_speed_large | long long |
timeout_ms | long |
connecttimeout_ms | long |
maxage_conn | long |
maxconnects | long |
use_ssl | long | none, try, control, all
resolve | list |
dns_servers | string |
accepttimeout_ms | long |
dns_interface | string |
dns_local_ip4 | string |
dns_local_ip6 | string |
connect_to | list |
happy_eyeballs_timeout_ms | long |
dns_shuffle_addresses | long |
upkeep_interval_ms | long |
maxlifetime_conn | long |
sslcert | string |
sslversion | long | default, tlsv1, sslv2, sslv3, tlsv1_0, tlsv1_1, tlsv1_2, tlsv1_3, max_default, max_none, max_tlsv1_0, max_tlsv1_1, max_tlsv1_2, max_tlsv1_3
ssl_verifypeer | long |
cainfo | string |
ssl_verifyhost | long |
ssl_cipher_list | string |
sslcerttype | string |
sslkey | string |
sslkeytype | string |
sslengine | string |
sslengine_default | long |
capath | string |
ssl_sessionid_cache | long |
keypasswd | string |
issuercert | string |
crlfile | string |
certinfo | long |
gssapi_delegation | long | none, policy_flag, flag
ssl_options | long | allow_beast, no_revoke, no_backends, ok, too_late, unknown_backend, no_partialchain, revoke_best_effort, native_ca, auto_client_cert
ssl_enable_alpn | long |
pinnedpublickey | string |
ssl_verifystatus | long |
proxy_cainfo | string |
proxy_capath | string |
proxy_crlfile | string |
proxy_keypasswd | string |
proxy_pinnedpublickey | string |
proxy_sslcert | string |
proxy_sslcerttype | string |
proxy_sslkey | string |
proxy_sslkeytype | string |
proxy_sslversion | long | default, tlsv1, sslv2, sslv3, tlsv1_0, tlsv1_1, tlsv1_2, tlsv1_3, max_default, max_none, max_tlsv1_0, max_tlsv1_1, max_tlsv1_2, max_tlsv1_3
proxy_ssl_cipher_list | list |
proxy_ssl_options | long | allow_beast, no_revoke, no_backends, ok, too_late, unknown_backend, no_partialchain, revoke_best_effort, native_ca, auto_client_cert
proxy_ssl_verifyhost | long |
proxy_ssl_verifypeer | long |
proxy_tlsauth_password | string |
proxy_tlsauth_type | string |
proxy_tlsauth_username | string |
tls13_ciphers | list |
proxy_tls13_ciphers | list |
proxy_issuercert | string |
ssl_ec_curves | string |
doh_ssl_verifyhost | long |
doh_ssl_verifypeer | long |
doh_ssl_verifystatus | long |
ca_cache_timeout | long |
ssh_auth_types | mask | none, policy_flag, flag
ssh_public_keyfile | string |
ssh_private_keyfile | string |
ssh_host_public_key_md5 | string |
ssh_knownhosts | string |
ssh_compression | long |
ssh_host_public_key_sha256 | string |
telnetoptions | list |
ws_options | mask | binary, close, cont, offset, ping, pong, raw_mode, text
new_file_perms | long |
new_directory_perms | long |
quick_exit | long |

注記 | (1) "mask" タイプのオプションでは、フォーマットは "value1+value2+value3" です。 "list" タイプのオプションでは、リスト要素を改行で区切ってください。 (`\n`). (2) 定数が利用可能な場合、定数は必ずオプションの値に含めてください。

These two extra options (strings) are allowed for input/output file:

Option | Type | Description
--- | --- | ---
file_in | string | 読み込んで URL に送信するファイル (ファイルを送信)
file_out | string | ダウンロードした URL/ファイルをこのファイルに書き込む (標準出力を使わない)

戻り値:

- 新しいフックへのポインタ、エラーが起きた場合は NULL

C 言語での使用例:

    int
    my_url_cb (const void *pointer, void *data, const char *url,
               struct t_hashtable *options, struct t_hashtable *output)
    {
        weechat_printf (NULL, "response_code: %s", weechat_hashtable_get (output, "response_code"));
        weechat_printf (NULL, "headers: %s", weechat_hashtable_get (output, "headers"));
        weechat_printf (NULL, "output: %s", weechat_hashtable_get (output, "output"));
        weechat_printf (NULL, "error: %s", weechat_hashtable_get (output, "error"));
        return WEECHAT_RC_OK;
    }

    /* example 1: output to a file */
    struct t_hashtable *options_url1 = weechat_hashtable_new (8,
                                                              WEECHAT_HASHTABLE_STRING,
                                                              WEECHAT_HASHTABLE_STRING,
                                                              NULL,
                                                              NULL);
    if (options_url1)
    {
        weechat_hashtable_set (options_url1, "file_out", "/tmp/weechat.org.html");
        struct t_hook *my_url_hook = weechat_hook_url ("https://weechat.org/",
                                                       options_url1,
                                                       20000,
                                                       &my_url_cb, NULL, NULL);
        weechat_hashtable_free (options_url1);
    }

    /* example 2: custom HTTP headers, output sent to callback */
    struct t_hashtable *options_url2 = weechat_hashtable_new (8,
                                                              WEECHAT_HASHTABLE_STRING,
                                                              WEECHAT_HASHTABLE_STRING,
                                                              NULL,
                                                              NULL);
    if (options_url2)
    {
        weechat_hashtable_set (options_url2, "httpheader",
                               "Header1: value1\n"
                               "Header2: value2");
        struct t_hook *my_url_hook = weechat_hook_url ("http://localhost:8080/",
                                                       options_url2,
                                                       20000,
                                                       &my_url_cb, NULL, NULL);
        weechat_hashtable_free (options_url2);
    }

スクリプト (Python) での使用例:

    # プロトタイプ
    def hook_url(url: str, options: Dict[str, str], timeout: int, callback: str, callback_data: str) -> str: ...

    # 例
    def my_url_cb(data: str, url: str, options: Dict[str, str], output: Dict[str, str]) -> int:
        weechat.prnt("", "output: %s" % output)
        return weechat.WEECHAT_RC_OK

    # example 1: output to a file
    hook1 = weechat.hook_url("https://weechat.org/",
                             {"file_out": "/tmp/weechat.org.html"},
                             20000, "my_url_cb", "")

    # example 2: custom HTTP headers, output sent to callback
    options = {
        "httpheader": "\n".join([
            "Header1: value1",
            "Header2: value2",
        ]),
    }
    hook2 = weechat.hook_url("http://localhost:8080/", options, 20000, "my_url_cb", "")

#### hook_connect

Updated in 1.5, 2.0, 4.4.0.

接続をフックする (リモートホストへのバックグラウンド接続)。

プロトタイプ:

    struct t_hook *weechat_hook_connect (const char *proxy,
                                         const char *address,
                                         int port,
                                         int ipv6,
                                         int retry,
                                         void *gnutls_sess,
                                         void *gnutls_cb,
                                         int gnutls_dhkey_size,
                                         const char *gnutls_priorities,
                                         const char *local_hostname,
                                         int (*callback)(const void *pointer,
                                                         void *data,
                                                         int status,
                                                         int gnutls_rc,
                                                         int sock,
                                                         const char *error,
                                                         const char *ip_address),
                                         const void *callback_pointer,
                                         void *callback_data);

引数:

- proxy: 接続に使用するプロキシの名前 (任意、プロキシを使わない場合は NULL)

- address: 接続先のドメイン名または IP アドレス

- port: ポート番号

- ipv6:

  - `WEECHAT_HOOK_CONNECT_IPV6_DISABLE` (1): disable IPv6 (use only IPv4)

  - `WEECHAT_HOOK_CONNECT_IPV6_AUTO` (1): use IPv6 with fallback to IPv4

  - `WEECHAT_HOOK_CONNECT_IPV6_FORCE` (1): force IPv6 (do not use IPv4) (WeeChat ≥ 4.4.0)

- retry: 再試行回数、IPv6 ホストに接続したもののクライアントの受け入れに失敗した際に IPv4 ホストへフォールバックする際に使う

- gnutls_sess: GnuTLS セッション (任意)

- gnutls_cb: GnuTLS コールバック (任意)

- gnutls_dhkey_size: Diffie-Hellman 鍵交換の際に使う鍵のサイズ (GnuTLS)

- gnutls_priorities: gnutls のプロパティ (構文は gnutls マニュアルの gnutls_priority_init 関数を参照)、基本的な値を以下に示す:

  - PERFORMANCE

  - NORMAL (デフォルト)

  - SECURE128

  - SECURE256

  - EXPORT

  - NONE

- local_hostname: 接続に使うローカルのホスト名前 (任意)

- callback: 接続に成功および失敗した際に呼び出すコールバック関数、引数と戻り値:

  - const void *pointer: ポインタ

  - void *data: ポインタ

  - int status: 接続状態 (2):

    - WEECHAT_HOOK_CONNECT_OK: 接続成功

    - WEECHAT_HOOK_CONNECT_ADDRESS_NOT_FOUND: アドレスが見つかりません

    - WEECHAT_HOOK_CONNECT_IP_ADDRESS_NOT_FOUND: IP アドレスが見つかりません

    - WEECHAT_HOOK_CONNECT_CONNECTION_REFUSED: 接続が拒否されました

    - WEECHAT_HOOK_CONNECT_PROXY_ERROR: プロキシに関するエラー

    - WEECHAT_HOOK_CONNECT_LOCAL_HOSTNAME_ERROR: ローカルのホスト名に関するエラー

    - WEECHAT_HOOK_CONNECT_GNUTLS_INIT_ERROR: GnuTLS 初期化エラー

    - WEECHAT_HOOK_CONNECT_GNUTLS_HANDSHAKE_ERROR: GnuTLS ハンドシェイクエラー

    - WEECHAT_HOOK_CONNECT_MEMORY_ERROR: メモリ不足

    - WEECHAT_HOOK_CONNECT_TIMEOUT: タイムアウト

    - WEECHAT_HOOK_CONNECT_SOCKET_ERROR: ソケットの作成に失敗

  - gnutls_rc: gnutls_handshake() の戻り値 (2)

  - sock: 接続に使うソケット (2)

  - const char *error: gnutls_strerror(gnutls_rc) の戻り値

  - const char *ip_address: 見つかった IP アドレス

  - 戻り値:

    - WEECHAT_RC_OK

    - WEECHAT_RC_ERROR

- callback_pointer: WeeChat が callback コールバックを呼び出す際にコールバックに渡すポインタ

- callback_data: WeeChat が callback コールバックを呼び出す際にコールバックに渡すポインタ; このポインタが NULL でない場合、このポインタは malloc (または類似の関数) によって割り当てられたものでなければいけません。さらに、このポインタはここで作成したフックが削除された時点で自動的に開放されます

注記 | (1) Constants for parameter ipv6 are available since WeeChat 4.4.0. For older releases, allowed values are `1` (use IPv6 with fallback to IPv4) and `0` (disable IPv6, use only IPv4). (2) スクリプトにおけるコールバック引数 status、gnutls_rc、sock は WeeChat バージョン 2.0 以上では整数、バージョン 1.9 以下では文字列です。 すべてのバージョンで互換性を保つには、使用前にコールバック引数 status、gnutls_rc、sock を整数へ変換することを推奨します (Python の場合 `int(sock)` のように変換してください)。

戻り値:

- 新しいフックへのポインタ、エラーが起きた場合は NULL

C 言語での使用例:

    int
    my_connect_cb (const void *pointer, void *data, int status, int gnutls_rc,
                   int sock, const char *error, const char *ip_address)
    {
        switch (status)
        {
            case WEECHAT_HOOK_CONNECT_OK:
                /* ... */
                break;
            case WEECHAT_HOOK_CONNECT_ADDRESS_NOT_FOUND:
                /* ... */
                break;
            case WEECHAT_HOOK_CONNECT_IP_ADDRESS_NOT_FOUND:
                /* ... */
                break;
            case WEECHAT_HOOK_CONNECT_CONNECTION_REFUSED:
                /* ... */
                break;
            case WEECHAT_HOOK_CONNECT_PROXY_ERROR:
                /* ... */
                break;
            case WEECHAT_HOOK_CONNECT_LOCAL_HOSTNAME_ERROR:
                /* ... */
                break;
            case WEECHAT_HOOK_CONNECT_GNUTLS_INIT_ERROR:
                /* ... */
                break;
            case WEECHAT_HOOK_CONNECT_GNUTLS_HANDSHAKE_ERROR:
                /* ... */
                break;
            case WEECHAT_HOOK_CONNECT_MEMORY_ERROR:
                /* ... */
                break;
            case WEECHAT_HOOK_CONNECT_TIMEOUT:
                /* ... */
                break;
            case WEECHAT_HOOK_CONNECT_SOCKET_ERROR:
                /* ... */
                break;
        }
        return WEECHAT_RC_OK;
    }

    struct t_hook *my_connect_hook = weechat_hook_connect (NULL,
                                                           "my.server.org", 1234,
                                                           WEECHAT_HOOK_CONNECT_IPV6_AUTO,
                                                           0,
                                                           NULL, NULL, 0,  /* GnuTLS */
                                                           NULL,
                                                           &my_connect_cb, NULL, NULL);

スクリプト (Python) での使用例:

    # プロトタイプ
    def hook_connect(proxy: str, address: str, port: int, ipv6: int, retry: int, local_hostname: str,
                     callback: str, callback_data: str) -> str: ...

    # 例
    def my_connect_cb(data: str, status: int, gnutls_rc: int, sock: int, error: str, ip_address: str) -> int:
        if status == weechat.WEECHAT_HOOK_CONNECT_OK:
            # ...
        elif status == weechat.WEECHAT_HOOK_CONNECT_ADDRESS_NOT_FOUND:
            # ...
        elif status == weechat.WEECHAT_HOOK_CONNECT_IP_ADDRESS_NOT_FOUND:
            # ...
        elif status == weechat.WEECHAT_HOOK_CONNECT_CONNECTION_REFUSED:
            # ...
        elif status == weechat.WEECHAT_HOOK_CONNECT_PROXY_ERROR:
            # ...
        elif status == weechat.WEECHAT_HOOK_CONNECT_LOCAL_HOSTNAME_ERROR:
            # ...
        elif status == weechat.WEECHAT_HOOK_CONNECT_GNUTLS_INIT_ERROR:
            # ...
        elif status == weechat.WEECHAT_HOOK_CONNECT_GNUTLS_HANDSHAKE_ERROR:
            # ...
        elif status == weechat.WEECHAT_HOOK_CONNECT_MEMORY_ERROR:
            # ...
        elif status == weechat.WEECHAT_HOOK_CONNECT_TIMEOUT:
            # ...
        elif status == weechat.WEECHAT_HOOK_CONNECT_SOCKET_ERROR:
            # ...
        return weechat.WEECHAT_RC_OK

    hook = weechat.hook_connect("", "my.server.org", 1234,
                                weechat.WEECHAT_HOOK_CONNECT_IPV6_AUTO, 0, "",
                                "my_connect_cb", "")

#### hook_line

WeeChat ≥ 2.3, updated in 4.2.0.

バッファに対する行表示をフックする。

バッファに行が表示される際に、以下の順番でフックが呼び出されます:

- hook line (このフック): バッファ、プレフィックス、メッセージ、タグ、通知レベル、… を変更可能 (以下を参照)

- hook modifier "weechat_print": フォーマット済み内容バッファ上のプレフィックスとメッセージを変更可能

- hook print: 行がフォーマット済み内容バッファに追加された時点で呼び出されます (このフックでは何かを変更することはできません)。

注記 | 上記 3 つのフックの中で、フォーマット済み内容バッファの内容を操作できるのは "line" フックだけです。

プロトタイプ:

    struct t_hook *weechat_hook_line (const char *buffer_type,
                                      const char *buffer_name,
                                      const char *tags,
                                      struct t_hashtable *(*callback)(const void *pointer,
                                                                      void *data,
                                                                      struct t_hashtable *line),
                                      const void *callback_pointer,
                                      void *callback_data);

引数:

- buffer_type: ここで指定したバッファ型の行をフックします (NULL または空文字列の場合、 formatted を指定したことになります) (WeeChat ≥ 3.7: a priority is allowed before the buffer type, see note about priority):

  - formatted: フォーマット済み内容バッファの行のみをフックします (デフォルト)

  - free: 自由内容バッファの行のみをフックします

  - *: すべてのバッファの行をフックします

- buffer_name: バッファマスクのコンマ区切りリスト (buffer_match_list を参照してください); NULL、空文字列、"*" は任意のバッファにマッチします。

- tags: 指定したタグを付けられたメッセージのみをフックします (任意): メッセージに含まれるタグのコンマ区切りリスト (論理 "or"); 複数のタグを論理 "and" で組み合わせるには `+` を使ってください; タグ中の `*` はワイルドカードを意味します

- callback: バッファに行が追加されると呼び出される関数、引数と戻り値は以下:

  - const void *pointer: ポインタ

  - void *data: ポインタ

  - struct t_hashtable *line: 行のインフォを含むハッシュテーブル、キーと値は文字列 (以下のテーブルを参照してください)

  - 戻り値: 新しい値のハッシュテーブル (以下のテーブルを参照してください)

- callback_pointer: WeeChat がコールバックを呼び出した際にコールバックに渡したポインタ

- callback_data: WeeChat がコールバックを呼び出した際にコールバックに渡したポインタ; NULL 以外の場合、このポインタの指す領域は malloc (もしくは類似の関数) で割り当てられたものでなければいけません。加えて、このポインタの指す領域はフックが削除された時点で自動的に解放されます。

戻り値:

- 新しいフックへのポインタ、エラーが起きた場合は NULL

コールバックへ送られる行のデータは以下の値を持つハッシュテーブルです (キーと値は文字列):

キー | 値 (フォーマット済みバッファ) | 値 (自由内容バッファ) | 例
--- | --- | --- | ---
buffer | バッファポインタ | バッファポインタ | `0x1234abcd`
buffer_name | バッファ名 | バッファ名 | `core.weechat` `irc.server.libera` `irc.libera.#weechat`
buffer_type | "formatted" | "free" | `formatted` `free`
y | 利用不可 ("-1") | 行番号 (≥ "0") | `-1` `8`
date | 行日付 (タイムスタンプ) | 利用不可 ("0") | `1533792000`
date_usec | Microseconds of line date (between 0 and 999999). | N/A ("0"). | `123456`
date_printed | 行が表示された日付 (タイムスタンプ) | 利用不可 ("0") | `1533792012`
date_usec_printed | Microseconds of date when line was displayed (between 0 and 999999). | N/A ("0"). | `654321`
str_time | 行に追加される日付 (色コードを入れてもよい) | 利用不可 (空文字列) | `09:07:20`
tags_count | タグの個数 (≥ "0") | 利用不可 ("0") | `2`
tags | タグのコンマ区切りリスト | 利用不可 (空文字列) | `irc_join,nick_test`
displayed | "0" = 行はフィルタされました (非表示) "1" = 行はフィルタされませんでした (表示) | "0" = 行はフィルタされました (非表示) "1" = 行はフィルタされませんでした (表示) | `0` `1`
notify_level | "-1" = no notify "0" = 低レベル "1" = メッセージ "2" = プライベートメッセージ "3" = ハイライト | 利用不可 ("0") | `2`
highlight | "0" = ハイライトなし "1" = ハイライトあり | 利用不可 ("0"). | `0` `1`
prefix | 行のプレフィックス | 利用不可 (空文字列) | `-->`
message | 行のメッセージ | 行のメッセージ | `test (~test@example.com) has joined #channel`

戻り値としては、値すべてのフィールドを含む完全なハッシュテーブルを返す必要もありませんし、無効なフィールドがあっても WeeChat はそれらを無視します。

ハッシュテーブルに設定できるキーを以下に挙げます (ハッシュテーブル中のキーと値は文字列です)。

キー | 設定可能な値 (フォーマット済みバッファ) | 設定可能な値 (自由内容バッファ) | 結果
--- | --- | --- | ---
buffer | フォーマット済みバッファへのポインタ | 自由内容バッファへのポインタ | 行を表示するバッファ。 この値が空の場合、行は削除されます (ハッシュテーブルに含まれるその他の情報も無視されます); "line" 型の次のフックも呼び出されません。
buffer_name | フォーマット済み内容バッファの名前. | 自由内容バッファの名前 | 行を表示するバッファ。 `buffer` と `buffer_name` の両方が設定された場合、`buffer_name` の値が優先されます この値が空の場合、行は削除されます (ハッシュテーブルに含まれるその他の情報も無視されます); "line" 型の次のフックも呼び出されません。
y | 利用不可 | 整数 (≥ "0") | 行番号はこの値に設定されます
date | タイムスタンプ | 利用不可 | 日付はこの値に設定されます これに対応して `str_time` も更新されます
date_usec | Integer ("0" to "999999"). | 利用不可 | The microseconds of line date is set to this value. これに対応して `str_time` も更新されます
date_printed | タイムスタンプ | 利用不可 | 表示される日付はこのタイムスタンプを使います。The printed date is set to this timestamp (not displayed).
date_usec_printed | Integer ("0" to "999999"). | 利用不可 | The microseconds of printed date is set to this value.
str_time | 文字列 | 利用不可 | この文字列は日付を表示する際に使われます。 `date` と `str_time` の両方が設定された場合、`str_time` の値が優先されます。
tags | 文字列 | 利用不可 | 行タグはここで指定したコンマ区切りリストに置き換えられます。 これに対応して `notify_level` と `highlight` も更新されます。
notify_level | 整数 ("-1" から "3") | 利用不可 | 通知レベルがこの値に設定されます。バッファに行が追加されるとホットリストも更新されます。 この値に対応して `highlight` の値も更新されます。 `tags` と `notify_level` の両方が設定された場合、`notify_level` の値が優先されます。
highlight | 整数 ("0" または "1") | 利用不可 | "0" は行のハイライトを無効化し、"1" は行のハイライトを強制します。 この値と `tags` または `notify_level` の両方が設定された場合、`highlight` の値が優先されます。
prefix | 文字列 | 利用不可 | 行のプレフィックスがこの値に設定されます
message | 文字列 | 文字列 | 行メッセージがこの値に設定されます

C 言語での使用例:

    int
    my_line_cb (const void *pointer, void *data, struct t_hashtable *line)
    {
        struct t_hashtable *hashtable;

        hashtable = weechat_hashtable_new (8,
                                           WEECHAT_HASHTABLE_STRING,
                                           WEECHAT_HASHTABLE_STRING,
                                           NULL,
                                           NULL);
        /* この行のハイライトを強制 */
        weechat_hashtable_set (hashtable, "highlight", "1");
        return hashtable;
    }

    /* タグ "irc_join" をつけられた行をフック */
    struct t_hook *my_line_hook =
        weechat_hook_line ("", "", "irc_join", &my_line_cb, NULL, NULL);

スクリプト (Python) での使用例:

    # プロトタイプ
    def hook_line(buffer_type: str, buffer_name: str, tags: str, callback: str, callback_data: str) -> str: ...

    # 例
    def my_line_cb(data: str, line: Dict[str, str]) -> Dict[str, str]:
        # この行のハイライトを強制
        return {"highlight": "1"}

    # タグ "irc_join" をつけられた行をフック
    hook = weechat.hook_line("", "", "irc_join", "my_line_cb", "")

#### hook_print

WeeChat バージョン 0.4.3、1.0、1.5、4.2.0 で更新。

メッセージの表示をフックする。これは行がフォーマット済みバッファに追加された時点で呼び出されます。

行が表示された際に呼び出されるフックの情報は hook_line を参照してください。

プロトタイプ:

    struct t_hook *weechat_hook_print (struct t_gui_buffer *buffer,
                                       const char *tags,
                                       const char *message,
                                       int strip_colors,
                                       int (*callback)(const void *pointer,
                                                       void *data,
                                                       struct t_gui_buffer *buffer,
                                                       time_t date,
                                                       int date_usec,
                                                       int tags_count,
                                                       const char **tags,
                                                       int displayed,
                                                       int highlight,
                                                       const char *prefix,
                                                       const char *message),
                                       const void *callback_pointer,
                                       void *callback_data);

引数:

- buffer: バッファへのポインタ、NULL の場合、任意のバッファからのメッセージをキャッチする

- tags: このタグが付けられたメッセージだけをキャッチする (任意):

  - WeeChat バージョン 0.4.3 以上の場合: メッセージに付けられたタグのコンマ区切りリスト (論理 "or"); 複数の条件を論理 "and" で組み合わせる場合は区切りに `+` を使ってください; ワイルドカード `*` を使うことができます

  - WeeChat バージョン 0.4.2 以下の場合: 論理 "and" で組み合わせたタグのコンマ区切りリスト

- message: この文字列を含むメッセージだけをキャッチする (任意、大文字小文字を区別しない)

- strip_colors: 1 の場合、コールバックを呼ぶ前に、表示されるメッセージから色を削除する

- callback: メッセージが表示される際に呼び出すコールバック関数、引数と戻り値:

  - const void *pointer: ポインタ

  - void *data: ポインタ

  - struct t_gui_buffer *buffer: バッファへのポインタ

  - time_t date: 日付

  - int date_usec: microseconds of date

  - int tags_count: 行に付けられたタグの個数

  - const char **tags: 行に付けられたタグの配列

  - int displayed: 行が表示される場合は 1、フィルタされる (隠される) 場合は 0

  - int highlight: 行がハイライトされる場合は 1、ハイライトされない場合は 0

  - const char *prefix: プレフィックス

  - const char *message: メッセージ

  - 戻り値:

    - WEECHAT_RC_OK

    - WEECHAT_RC_ERROR

- callback_pointer: WeeChat が callback コールバックを呼び出す際にコールバックに渡すポインタ

- callback_data: WeeChat が callback コールバックを呼び出す際にコールバックに渡すポインタ; このポインタが NULL でない場合、このポインタは malloc (または類似の関数) によって割り当てられたものでなければいけません。さらに、このポインタはここで作成したフックが削除された時点で自動的に開放されます

戻り値:

- 新しいフックへのポインタ、エラーが起きた場合は NULL

重要 | スクリプトにおけるコールバック引数 displayed、highlight は WeeChat バージョン 1.0 以上では整数、バージョン 0.4.3 以下では文字列です。 すべてのバージョンで互換性を保つには、使用前にコールバック引数 displayed、highlight を整数へ変換することを推奨します (Python の場合 `if int(highlight):` のように変換してください)。

C 言語での使用例:

    int
    my_print_cb (const void *pointer, void *data, struct t_gui_buffer *buffer,
                 time_t date, int date_usec, int tags_count, const char **tags,
                 int displayed, int highlight,
                 const char *prefix, const char *message)
    {
        /* ... */
        return WEECHAT_RC_OK;
    }

    /* catch all messages, on all buffers, without color */
    struct t_hook *my_print_hook =
        weechat_hook_print (NULL, NULL, NULL, 1, &my_print_cb, NULL, NULL);

スクリプト (Python) での使用例:

    # プロトタイプ
    def hook_print(buffer: str, tags: str, message: str, strip_colors: int, callback: str, callback_data: str) -> str: ...

    # 例
    def my_print_cb(data: str, buffer: str, date: str, tags: str, displayed: int, highlight: int, prefix: str, message: str) -> int:
        if highlight:
            # ...
        return weechat.WEECHAT_RC_OK

    # catch all messages, on all buffers, without color
    hook = weechat.hook_print("", "", "", 1, "my_print_cb", "")

#### hook_signal

WeeChat バージョン 1.5, 3.6 で更新。

シグナルをフックする。

プロトタイプ:

    struct t_hook *weechat_hook_signal (const char *signal,
                                        int (*callback)(const void *pointer,
                                                        void *data,
                                                        const char *signal,
                                                        const char *type_data,
                                                        void *signal_data),
                                        const void *callback_pointer,
                                        void *callback_data);

引数:

- signal: キャッチするシグナル、ワイルドカード `*` を使うことができます, multiple signals can be separated by semi-colons (a priority is allowed before one or more signals, see note about priority) (以下の表を参照)

- callback: シグナルを受信した際に呼び出すコールバック関数、引数と戻り値:

  - const void *pointer: ポインタ

  - void *data: ポインタ

  - const char *signal: 受信したシグナル

  - const char *type_data: シグナルが送信したデータの型

    - WEECHAT_HOOK_SIGNAL_STRING: 文字列

    - WEECHAT_HOOK_SIGNAL_INT: 整数

    - WEECHAT_HOOK_SIGNAL_POINTER: ポインタ

  - void *signal_data: シグナルが送信したデータ

  - 戻り値:

    - WEECHAT_RC_OK

    - WEECHAT_RC_OK_EAT (直ちにシグナルの送信を止める) (WeeChat バージョン 0.4.0 以上で利用可)

    - WEECHAT_RC_ERROR

- callback_pointer: WeeChat が callback コールバックを呼び出す際にコールバックに渡すポインタ

- callback_data: WeeChat が callback コールバックを呼び出す際にコールバックに渡すポインタ; このポインタが NULL でない場合、このポインタは malloc (または類似の関数) によって割り当てられたものでなければいけません。さらに、このポインタはここで作成したフックが削除された時点で自動的に開放されます

戻り値:

- 新しいフックへのポインタ、エラーが起きた場合は NULL

WeeChat とプラグインが送信するシグナルのリスト:

プラグイン | シグナル | Min WeeChat | 引数 | 説明
--- | --- | --- | --- | ---
guile | guile_script_loaded | 0.3.9 | String: スクリプトへのパス | Scheme スクリプトをロード
guile | guile_script_unloaded | 0.3.9 | String: スクリプトへのパス | Scheme スクリプトをリロード
guile | guile_script_installed | 0.3.9 | String: インストールされたスクリプトへのパスのコンマ区切りリスト | Scheme スクリプトをインストール
guile | guile_script_removed | 0.3.9 | String: 削除されたスクリプトへのパスのコンマ区切りリスト | Scheme スクリプトを削除
irc | xxx,irc_in_yyy (1) |  | String: メッセージ | サーバから IRC メッセージを受信 (メッセージを 無視しない 場合のみ irc プラグインがメッセージを処理する前に、シグナルが送信される) バージョン 2.2 以上ではタグを含めたすべての IRC メッセージが送信されます。 If the return code of a callback is WEECHAT_RC_OK_EAT, then the IRC message is immediately destroyed and not processed (WeeChat ≥ 3.3).
irc | xxx,irc_in2_yyy (1) |  | String: メッセージ | サーバから IRC メッセージを受信 (メッセージを 無視しない 場合のみ irc プラグインがメッセージを処理した後に、シグナルが送信される) バージョン 2.2 以上ではタグを含めたすべての IRC メッセージが送信されます。
irc | xxx,irc_raw_in_yyy (1) | 0.3.2 | String: メッセージ | サーバから IRC メッセージを受信 (メッセージを無視する場合でも irc プラグインがメッセージを処理する前に、シグナルが送信される) バージョン 2.2 以上ではタグを含めたすべての IRC メッセージが送信されます。 If the return code of a callback is WEECHAT_RC_OK_EAT, then the IRC message is immediately destroyed and not processed (WeeChat ≥ 3.3).
irc | xxx,irc_raw_in2_yyy (1) | 0.3.2 | String: メッセージ | サーバから IRC メッセージを受信 (メッセージを無視する場合でも irc プラグインがメッセージを処理した後に、シグナルが送信される) バージョン 2.2 以上ではタグを含めたすべての IRC メッセージが送信されます。
irc | xxx,irc_out1_yyy (1) | 0.3.7 | String: メッセージ | サーバに送信する IRC メッセージ (自動分割前、自動分割はデフォルトでメッセージを 512 バイト内に収まるように分割します)。
irc | xxx,irc_out_yyy (1) |  | String: メッセージ | サーバに送信する IRC メッセージ (自動分割後、自動分割はデフォルトでメッセージを 512 バイト内に収まるように分割します)。 Warning: the string may contain invalid UTF-8 data. Signal "xxx,irc_out1_yyy" is recommended instead.
irc | xxx,irc_outtags_yyy (1) | 0.3.4 | String: タグ + ";" + メッセージ | タグ + サーバに送信する IRC メッセージ Warning: the string may contain invalid UTF-8 data. Signal "xxx,irc_out1_yyy" is recommended instead.
irc | irc_ctcp |  | String: メッセージ | CTCP を受信
irc | irc_dcc |  | String: メッセージ | 新しい DCC
irc | irc_pv |  | String: メッセージ | プライベートメッセージを受信
irc | irc_channel_opened |  | Pointer: バッファ | チャンネルを開いた
irc | irc_pv_opened |  | Pointer: バッファ | プライベートメッセージを開いた
irc | irc_server_opened | 0.3.7 | Pointer: バッファ | サーババッファを開いた
irc | irc_server_connecting |  | String: サーバ名 | サーバに接続中
irc | irc_server_connected |  | String: サーバ名 | サーバとの接続を確立
irc | irc_server_disconnected |  | String: サーバ名 | サーバから切断された
irc | irc_server_lag_changed | 1.8 | String: サーバ名 | 指定したサーバの遅延時間が変化
irc | irc_ignore_removing |  | Pointer: 無視 | 無視条件を削除中
irc | irc_ignore_removed |  | - | 無視条件を削除した
irc | irc_notify_join | 0.3.8 | String: サーバ名 + "," + ニックネーム | 通知リストに入っているニックネームがサーバに参加
irc | irc_notify_quit | 0.3.8 | String: サーバ名 + "," + ニックネーム | 通知リストに入っているニックネームがサーバから切断
irc | irc_notify_away | 0.3.8 | String: サーバ名 + "," + ニックネーム + "," + 離席メッセージ | 通知リストに入っているニックネームが離席状態に
irc | irc_notify_still_away | 0.3.8 | String: サーバ名 + "," + ニックネーム + "," + 離席メッセージ | 通知リストに入っているニックネームはまだ離席状態 (離席メッセージを変更)
irc | irc_notify_back | 0.3.8 | String: サーバ名 + "," + ニックネーム | 通知リストに入っているニックネームが着席状態に (離席状態を解除)
javascript | javascript_script_loaded | 1.2 | String: スクリプトへのパス | JavaScript スクリプトをロード
javascript | javascript_script_unloaded | 1.2 | String: スクリプトへのパス | JavaScript スクリプトをリロード
javascript | javascript_script_installed | 1.2 | String: インストールされたスクリプトへのパスのコンマ区切りリスト | JavaScript スクリプトをインストール
javascript | javascript_script_removed | 1.2 | String: 削除されたスクリプトへのパスのコンマ区切りリスト | JavaScript スクリプトを削除
logger | logger_start |  | Pointer: バッファ | バッファのログ保存を開始
logger | logger_stop |  | Pointer: バッファ | バッファのログ保存を中止
logger | logger_backlog |  | Pointer: バッファ | バッファのバックログを表示
lua | lua_script_loaded | 0.3.9 | String: スクリプトへのパス | Lua スクリプトをロード
lua | lua_script_unloaded | 0.3.9 | String: スクリプトへのパス | Lua スクリプトをリロード
lua | lua_script_installed | 0.3.9 | String: インストールされたスクリプトへのパスのコンマ区切りリスト | Lua スクリプトをインストール
lua | lua_script_removed | 0.3.9 | String: 削除されたスクリプトへのパスのコンマ区切りリスト | Lua スクリプトを削除
perl | perl_script_loaded | 0.3.9 | String: スクリプトへのパス | Perl スクリプトをロード
perl | perl_script_unloaded | 0.3.9 | String: スクリプトへのパス | Perl スクリプトをリロード
perl | perl_script_installed | 0.3.9 | String: インストールされたスクリプトへのパスのコンマ区切りリスト | Perl スクリプトをインストール
perl | perl_script_removed | 0.3.9 | String: 削除されたスクリプトへのパスのコンマ区切りリスト | Perl スクリプトを削除
php | php_script_loaded | 2.0 | String: スクリプトへのパス | PHP スクリプトをロード
php | php_script_unloaded | 2.0 | String: スクリプトへのパス | PHP スクリプトをリロード
php | php_script_installed | 2.0 | String: インストールされたスクリプトへのパスのコンマ区切りリスト | PHP スクリプトをインストール
php | php_script_removed | 2.0 | String: 削除されたスクリプトへのパスのコンマ区切りリスト | PHP スクリプトを削除
python | python_script_loaded | 0.3.9 | String: スクリプトへのパス | Python スクリプトをロード
python | python_script_unloaded | 0.3.9 | String: スクリプトへのパス | Python スクリプトをリロード
python | python_script_installed | 0.3.9 | String: インストールされたスクリプトへのパスのコンマ区切りリスト | Python スクリプトをインストール
python | python_script_removed | 0.3.9 | String: 削除されたスクリプトへのパスのコンマ区切りリスト | Python スクリプトを削除
relay | relay_client_connecting | 1.0 | Pointer: リレークライアント | リレークライアントが接続中
relay | relay_client_waiting_auth | 1.0 | Pointer: リレークライアント | リレークライアントからの認証待ち
relay | relay_client_auth_ok | 1.0 | Pointer: リレークライアント | リレークライアントからの認証に成功
relay | relay_client_connected | 1.0 | Pointer: リレークライアント | リレークライアントが接続
relay | relay_client_auth_failed | 1.0 | Pointer: リレークライアント | リレークライアントの認証に失敗
relay | relay_client_disconnected | 1.0 | Pointer: リレークライアント | リレークライアントが切断
ruby | ruby_script_loaded | 0.3.9 | String: スクリプトへのパス | Ruby スクリプトをロード
ruby | ruby_script_unloaded | 0.3.9 | String: スクリプトへのパス | Ruby スクリプトをリロード
ruby | ruby_script_installed | 0.3.9 | String: インストールされたスクリプトへのパスのコンマ区切りリスト | Ruby スクリプトをインストール
ruby | ruby_script_removed | 0.3.9 | String: 削除されたスクリプトへのパスのコンマ区切りリスト | Ruby スクリプトを削除
spell | spell_suggest | 2.4 | Pointer: バッファ | スペルの間違っている単語に対する新しい修正候補
tcl | tcl_script_loaded | 0.3.9 | String: スクリプトへのパス | Tcl スクリプトをロード
tcl | tcl_script_unloaded | 0.3.9 | String: スクリプトへのパス | Tcl スクリプトをリロード
tcl | tcl_script_installed | 0.3.9 | String: インストールされたスクリプトへのパスのコンマ区切りリスト | Tcl スクリプトをインストール
tcl | tcl_script_removed | 0.3.9 | String: 削除されたスクリプトへのパスのコンマ区切りリスト | Tcl スクリプトを削除
typing | typing_self_typing | 3.3 | Pointer: buffer. | User is typing a message (sent by typing plugin, used by irc plugin).
typing | typing_self_paused | 3.3 | Pointer: buffer. | User paused during typing (sent by typing plugin, used by irc plugin).
typing | typing_self_cleared | 3.3 | Pointer: buffer. | User cleared the input without sending the message (sent by typing plugin, used by irc plugin).
typing | typing_self_sent | 3.3 | Pointer: buffer. | Message (not a command) sent to the buffer (sent by typing plugin, used by irc plugin).
typing | typing_set_nick | 3.3 | String: buffer pointer + ";" + state (one of: "off", "typing", "paused", "cleared") + ";" + nick. | Set typing state for a nick on a buffer (sent by irc plugin, handled by typing plugin).
typing | typing_reset_buffer | 3.3 | Pointer: buffer. | Remove typing state for all nicks on a buffer (sent by irc plugin, handled by typing plugin).
weechat | buffer_opened |  | Pointer: バッファ | バッファを開いた
weechat | buffer_closing |  | Pointer: バッファ | バッファを閉じている
weechat | buffer_closed |  | Pointer: バッファ | バッファを閉じた
weechat | buffer_cleared |  | Pointer: バッファ | バッファをクリア
weechat | buffer_filters_enabled | 2.0 | Pointer: バッファ | バッファでフィルタが有効化されています。
weechat | buffer_filters_disabled | 2.0 | Pointer: バッファ | バッファでフィルタが無効化されています。
weechat | buffer_hidden |  | Pointer: バッファ | バッファを隠す
weechat | buffer_unhidden |  | Pointer: バッファ | バッファを隠すことを止める
weechat | buffer_line_added | 0.3.7 | Pointer: 行 | バッファに行を追加
weechat | buffer_line_data_changed | 4.4.0 | Pointer: line data. | Line data has been updated in a buffer.
weechat | buffer_lines_hidden |  | Pointer: バッファ | バッファから行を隠す
weechat | buffer_localvar_added |  | Pointer: バッファ | ローカル変数を追加
weechat | buffer_localvar_changed |  | Pointer: バッファ | ローカル変数を変更
weechat | buffer_localvar_removed |  | Pointer: バッファ | ローカル変数を削除
weechat | buffer_merged |  | Pointer: バッファ | バッファをマージ
weechat | buffer_unmerged |  | Pointer: バッファ | バッファのマージを解除
weechat | buffer_moved |  | Pointer: バッファ | バッファを移動
weechat | buffer_renamed |  | Pointer: バッファ | バッファの名前を変更
weechat | buffer_switch |  | Pointer: バッファ | バッファを切り替え
weechat | buffer_title_changed |  | Pointer: バッファ | バッファのタイトルを変更
weechat | buffer_modes_changed | 4.3.0 | Pointer: buffer. | Modes of buffer changed.
weechat | buffer_time_for_each_line_changed | 4.4.0 | Pointer: buffer. | Display time for each line changed.
weechat | buffer_type_changed |  | Pointer: バッファ | バッファのタイプを変更
weechat | buffer_zoomed | 0.4.3 | Pointer: バッファ | マージされたバッファをズーム
weechat | buffer_unzoomed | 0.4.3 | Pointer: バッファ | マージされたバッファをアンズーム
weechat | buffer_user_input_xxx (2) | 3.8 | String: text sent to buffer. | Text sent to a user buffer as input (sent only for buffers created with `/buffer add`). If the return code of a callback is WEECHAT_RC_OK_EAT, then the string "q" cannot be used anymore to close the buffer.
weechat | buffer_user_closing_xxx (2) | 3.8 | - | User buffer is closing (sent only for buffers created with `/buffer add`).
weechat | cursor_start | 3.2 | - | Start cursor mode.
weechat | cursor_end | 3.2 | - | End cursor mode.
weechat | day_changed | 0.3.2 | String: 新しい日付、書式: "2010-01-31" | システムの日付が変更された
weechat | debug_dump |  | String: プラグイン名 | リクエストをダンプ
weechat | debug_libs |  | - | 使用中の外部ライブラリを表示
weechat | filter_added |  | Pointer: フィルタ | フィルタを追加
weechat | filter_removing |  | Pointer: フィルタ | フィルタを削除中
weechat | filter_removed |  | - | フィルタを削除
weechat | filters_enabled |  | - | フィルタを有効化
weechat | filters_disabled |  | - | フィルタを無効化
weechat | hotlist_changed |  | Pointer: バッファ (NULL も可) | ホットリストが変更された
weechat | input_paste_pending |  | - | ペーストを保留中
weechat | input_search |  | Pointer: バッファ | バッファテキストの検索
weechat | input_prompt_changed | 4.3.0 | Pointer: buffer. | Input prompt changed.
weechat | input_text_changed |  | Pointer: バッファ | 入力テキストが変更された
weechat | input_text_cursor_moved |  | Pointer: バッファ | 入力テキストカーソルを移動
weechat | key_bind |  | String: キー | キー割り当てを追加
weechat | key_unbind |  | String: キー | キー割り当てを削除
weechat | key_pressed |  | String: 押されたキー | キーが押された
weechat | key_combo_default | 1.0 | String: キーの組み合わせ | default コンテキスト内のキーの組み合わせ
weechat | key_combo_search | 1.0 | String: キーの組み合わせ | search コンテキスト内のキーの組み合わせ
weechat | key_combo_cursor | 1.0 | String: キーの組み合わせ | cursor コンテキスト内のキーの組み合わせ
weechat | layout_buffers_applied | 4.4.0 | String: layout name. | Layout applied for buffers.
weechat | layout_windows_applied | 4.4.0 | String: layout name. | Layout applied for windows.
weechat | mouse_enabled | 1.1 | - | マウスが有効化された
weechat | mouse_disabled | 1.1 | - | マウスが無効化された
weechat | nicklist_group_added | 0.3.2 | String: バッファポインタ + "," + グループ名 | ニックネームリストにグループを追加
weechat | nicklist_group_changed | 0.3.4 | String: バッファポインタ + "," + グループ名 | ニックネームリストのグループを変更
weechat | nicklist_group_removing | 0.4.1 | String: バッファポインタ + "," + グループ名 | ニックネームリストからグループを削除中
weechat | nicklist_group_removed | 0.3.2 | String: バッファポインタ + "," + グループ名 | ニックネームリストからグループを削除
weechat | nicklist_nick_added | 0.3.2 | String: バッファポインタ + "," + ニックネーム | ニックネームリストにニックネームを追加
weechat | nicklist_nick_changed | 0.3.4 | String: バッファポインタ + "," + ニックネーム | ニックネームリストのニックネームを変更
weechat | nicklist_nick_removing | 0.4.1 | String: バッファポインタ + "," + ニックネーム | ニックネームリストからニックネームを削除中
weechat | nicklist_nick_removed | 0.3.2 | String: バッファポインタ + "," + ニックネーム | ニックネームリストからニックネームを削除
weechat | partial_completion |  | - | 部分補完を実行
weechat | plugin_loaded | 0.3.9 | String: 読み込んだプラグインへのパス | プラグインをロード
weechat | plugin_unloaded | 0.3.9 | String: リロードしたプラグインの名前 (例: "irc") | プラグインをリロード
weechat | quit |  | String: /quit の引数 | ユーザがコマンド `/quit` を実行
weechat | signal_sighup | 1.3 | - | SIGHUP シグナルを受信
weechat | signal_sigquit | 1.2 | - | SIGQUIT シグナルを受信 (コアダンプ付きで終了要求)
weechat | signal_sigterm | 1.2 | - | SIGTERM シグナルを受信 (WeeChat プロセスを正常に終了させる)
weechat | signal_sigwinch | 0.4.3 | - | SIGWINCH シグナルを受信しました (端末サイズが変更されました)
weechat | upgrade |  | String: "quit" if "-quit" argument was given for /upgrade, "save" if "-save" if "-save" argument was given for /upgrade, otherwise NULL. | ユーザがコマンド `/upgrade` を実行
weechat | upgrade_ended | 0.3.4 | - | アップグレード作業 (コマンド `/upgrade`) が終了
weechat | weechat_highlight |  | String: プレフィックス付のメッセージ | メッセージがハイライトされました
weechat | weechat_pv |  | String: プレフィックス付のメッセージ | プライベートメッセージの表示
weechat | window_closing | 0.3.6 | Pointer: ウィンドウ | ウィンドウを閉じています
weechat | window_closed | 0.3.6 | Pointer: ウィンドウ | ウィンドウを閉じた
weechat | window_opened | 0.4.1 | Pointer: ウィンドウ | ウィンドウを開いた
weechat | window_scrolled |  | Pointer: ウィンドウ | ウィンドウをスクロール
weechat | window_switch | 0.3.7 | Pointer: ウィンドウ | ウィンドウを切り替え
weechat | window_zoom |  | Pointer: 現在のウィンドウ | ウィンドウをズーム中
weechat | window_zoomed |  | Pointer: 現在のウィンドウ | ウィンドウをズーム
weechat | window_unzoom |  | Pointer: 現在のウィンドウ | ウィンドウのズームを元に戻している
weechat | window_unzoomed |  | Pointer: 現在のウィンドウ | ウィンドウのズームを元に戻す
xfer | xfer_add |  | Pointer: xfer インフォを含むインフォリスト | 新しい xfer
xfer | xfer_send_ready |  | Pointer: xfer インフォを含むインフォリスト | Xfer の準備完了
xfer | xfer_accept_resume |  | Pointer: xfer インフォを含むインフォリスト | Xfer のレジュームを受け入れる
xfer | xfer_send_accept_resume |  | Pointer: xfer インフォを含むインフォリスト | Xfer のレジュームの受け入れを完了
xfer | xfer_start_resume |  | Pointer: xfer インフォを含むインフォリスト | レジュームの開始
xfer | xfer_resume_ready |  | Pointer: xfer インフォを含むインフォリスト | Xfer レジュームの準備完了
xfer | xfer_ended | 0.3.2 | Pointer: xfer インフォを含むインフォリスト | Xfer を終了

注記 | (1) xxx はサーバ名、yyy は IRC コマンド名。 (2) xxx is buffer name.

C 言語での使用例:

    int
    my_signal_cb (const void *pointer, void *data, const char *signal,
                  const char *type_data, void *signal_data)
    {
        /* ... */
        return WEECHAT_RC_OK;
    }

    /* catch signals "quit" and "upgrade" */
    struct t_hook *my_signal_hook = weechat_hook_signal ("quit;upgrade",
                                                         &my_signal_cb, NULL, NULL);

スクリプト (Python) での使用例:

    # プロトタイプ
    def hook_signal(signal: str, callback: str, callback_data: str) -> str: ...

    # 例
    def my_signal_cb(data: str, signal: str, signal_data: str) -> int:
        # ...
        return weechat.WEECHAT_RC_OK

    # catch signals "quit" and "upgrade"
    hook = weechat.hook_signal("quit;upgrade", "my_signal_cb", "")

#### hook_signal_send

WeeChat バージョン 1.0, 4.5.0 で更新。

シグナルを送信。

プロトタイプ:

    int weechat_hook_signal_send (const char *signal, const char *type_data,
                                  void *signal_data);

引数:

- signal: 送信するシグナル; flags are allowed before the signal name (see below) (WeeChat ≥ 4.5.0)

- type_data: シグナルと一緒に送信するデータの型 (hook_signal を参照)

- signal_data: シグナルと一緒に送信するデータ

The signal name can contain flags with the following format: `[flags:xxx,yyy]signal` where `xxx` and `yyy` are names of flags, and `signal` the signal name.
The following flags are supported:

- stop_on_error: exit immediately if a callback returns WEECHAT_RC_ERROR (remaining callbacks are then NOT executed) (WeeChat ≥ 4.5.0)

- ignore_eat: consider any callback returning WEECHAT_RC_OK_EAT is in fact WEECHAT_RC_OK and execute remaining callbacks (WeeChat ≥ 4.5.0)

戻り値 (WeeChat バージョン 1.0 以上で利用可):

- 最後に実行したコールバックの戻り値 (コールバックを実行しなかった場合は WEECHAT_RC_OK):

  - WEECHAT_RC_OK

  - WEECHAT_RC_OK_EAT

  - WEECHAT_RC_ERROR

C 言語での使用例:

    int rc = weechat_hook_signal_send ("my_signal", WEECHAT_HOOK_SIGNAL_STRING, my_string);
    int rc2 = weechat_hook_signal_send ("[flags:stop_on_error,ignore_eat]my_signal2",
                                        WEECHAT_HOOK_SIGNAL_STRING, my_string);

スクリプト (Python) での使用例:

    # プロトタイプ
    def hook_signal_send(signal: str, type_data: str, signal_data: str) -> int: ...

    # 例
    rc = weechat.hook_signal_send("my_signal", weechat.WEECHAT_HOOK_SIGNAL_STRING, my_string)
    rc2 = weechat.hook_signal_send("[flags:stop_on_error,ignore_eat]my_signal2",
                                   weechat.WEECHAT_HOOK_SIGNAL_STRING, my_string)

##### logger_backlog シグナル

シグナル "logger_backlog" はバッファにバックログ (チャット履歴) を表示するために送信することができます (例えば、プラグインやスクリプトでバッファを開く際など)。

引数はバッファへのポインタ。

C 言語での使用例:

    weechat_hook_signal_send ("logger_backlog", WEECHAT_HOOK_SIGNAL_POINTER, buffer);

スクリプト (Python) での使用例:

    weechat.hook_signal_send("logger_backlog", weechat.WEECHAT_HOOK_SIGNAL_POINTER, buffer)

##### xxx_script_install シグナル

プログラミング言語ごとに、スクリプトをインストールするために送信するシグナルが 5 種類あります:

- perl_script_install

- python_script_install

- ruby_script_install

- lua_script_install

- tcl_script_install

- guile_script_install

- javascript_script_install

- php_script_install

シグナルを受け取ったらコールバックは以下のように働きます:

1. インストール済みスクリプトをリロードして削除。

2. 新しいスクリプトをディレクトリ ~/.local/share/weechat/xxx/ に移動 (xxx はプログラミング言語)

3. 新しいスクリプトへのリンクをディレクトリ ~/.local/share/weechat/xxx/autoload/ に作成 (古いスクリプトがすでに自動ロードされていた場合、もしくは新しいスクリプトに対してオプション script.scripts.autoload が有効化されている場合のみ作成されます)

4. 新しいスクリプトを読み込む (古いスクリプトがロードされていた場合のみ)

script プラグインはスクリプトをインストールする際にこれらのシグナルを使っています。

引数はインストールするスクリプトのパスを収めた文字列です。

C 言語での使用例:

    weechat_hook_signal_send ("python_script_install", WEECHAT_HOOK_SIGNAL_STRING, "/path/to/test.py");

スクリプト (Python) での使用例:

    weechat.hook_signal_send("python_script_install", WEECHAT_HOOK_SIGNAL_STRING, "/path/to/test.py")

##### xxx_script_remove シグナル

プログラミング言語ごとに、リスト文字列に含まれるスクリプトを削除するために送信するシグナルが 5 種類あります:

- perl_script_remove

- python_script_remove

- ruby_script_remove

- lua_script_remove

- tcl_script_remove

- guile_script_remove

- javascript_script_remove

- php_script_remove

リスト文字列に含まれるそれぞれのスクリプトについて、コールバックはスクリプトをリロードして削除します。

script プラグインはスクリプトを削除する際にこれらのシグナルを使っています。

引数は削除したいスクリプトのコンマ区切りリスト文字列です (パスを含まないスクリプトの名前を使います、例えば script.py).

C 言語での使用例:

    /* unload and remove scripts test.py and script.py */
    weechat_hook_signal_send ("python_script_remove", WEECHAT_HOOK_SIGNAL_STRING,
                              "test.py,script.py");

スクリプト (Python) での使用例:

    # unload and remove scripts test.py and script.py
    weechat.hook_signal_send("python_script_remove", WEECHAT_HOOK_SIGNAL_STRING,
                             "test.py,script.py")

##### irc_input_send シグナル

WeeChat バージョン 0.3.4 以上で利用可、バージョン 1.5 で更新。

irc バッファ(サーバ、チャンネル、プライベート) への入力をシミュレートするにはシグナル "irc_input_send" を送信してください。

引数は以下の書式に従う文字列です:

- 内部サーバ名 (必須)

- セミコロン

- チャンネル名 (任意)

- セミコロン

- オプションのコンマ区切りリスト (任意):

  - priority_high: キューに高い優先度を設定 (ユーザメッセージなど); 特に設定しなければこの優先度が設定されます

  - priority_low: キューに低い優先度を設定 (WeeChat が自動的に送信するメッセージなど)

  - user_message: 強制的にユーザメッセージ化 (コマンドを実行しません)

- セミコロン

- メッセージを送信する際に使うタグのコンマ区切りリスト (任意)

- セミコロン

- テキストまたはコマンド (必須)

C 言語での使用例:

    /* say "Hello!" on libera server, #weechat channel */
    weechat_hook_signal_send ("irc_input_send", WEECHAT_HOOK_SIGNAL_STRING,
                              "libera;#weechat;priority_high,user_message;;Hello!");

    /* send command "/whois FlashCode" on libera server, with low priority */
    weechat_hook_signal_send ("irc_input_send", WEECHAT_HOOK_SIGNAL_STRING,
                              "libera;;priority_low;;/whois FlashCode");

スクリプト (Python) での使用例:

    # say "Hello!" on libera server, #weechat channel
    weechat.hook_signal_send("irc_input_send", weechat.WEECHAT_HOOK_SIGNAL_STRING,
                             "libera;#weechat;priority_high,user_message;;Hello!")

    # send command "/whois FlashCode" on libera server, with low priority
    weechat.hook_signal_send("irc_input_send", weechat.WEECHAT_HOOK_SIGNAL_STRING,
                             "libera;;priority_low;;/whois FlashCode")

#### hook_hsignal

WeeChat バージョン 0.3.4 以上で利用可、バージョン 1.5, 3.6 で更新。

hsignal (ハッシュテーブルを持つシグナル) をフック。

プロトタイプ:

    struct t_hook *weechat_hook_hsignal (const char *signal,
                                         int (*callback)(const void *pointer,
                                                         void *data,
                                                         const char *signal,
                                                         struct t_hashtable *hashtable),
                                         const void *callback_pointer,
                                         void *callback_data);

引数:

- signal: キャッチするシグナル、ワイルドカード `*` を使うことができます, multiple signals can be separated by semi-colons (a priority is allowed before one or more signals, see note about priority) (以下の表を参照)

- callback: シグナルを受信した際に呼び出すコールバック関数、引数と戻り値:

  - const void *pointer: ポインタ

  - void *data: ポインタ

  - const char *signal: 受信したシグナル

  - struct t_hashtable *hashtable: ハッシュテーブル

  - 戻り値:

    - WEECHAT_RC_OK

    - WEECHAT_RC_OK_EAT (直ちにシグナルの送信を止める) (WeeChat バージョン 0.4.0 以上で利用可)

    - WEECHAT_RC_ERROR

- callback_pointer: WeeChat が callback コールバックを呼び出す際にコールバックに渡すポインタ

- callback_data: WeeChat が callback コールバックを呼び出す際にコールバックに渡すポインタ; このポインタが NULL でない場合、このポインタは malloc (または類似の関数) によって割り当てられたものでなければいけません。さらに、このポインタはここで作成したフックが削除された時点で自動的に開放されます

戻り値:

- 新しいフックへのポインタ、エラーが起きた場合は NULL

hsignal のリスト:

プラグイン | シグナル | Min WeeChat | 引数 | 説明
--- | --- | --- | --- | ---
irc | irc_redirection_xxx_yyy (1) | 0.3.4 | hsignal_irc_redirect_command を参照 | 出力の転送
weechat | nicklist_group_added | 0.4.1 | buffer (struct t_gui_buffer *): バッファ parent_group (struct t_gui_nick_group *): 親グループ group (struct t_gui_nick_group *): グループ | ニックネームリストにグループを追加
weechat | nicklist_nick_added | 0.4.1 | buffer (struct t_gui_buffer *): バッファ parent_group (struct t_gui_nick_group *): 親グループ nick (struct t_gui_nick *): ニックネーム | ニックネームリストにニックネームを追加
weechat | nicklist_group_removing | 0.4.1 | buffer (struct t_gui_buffer *): バッファ parent_group (struct t_gui_nick_group *): 親グループ group (struct t_gui_nick_group *): グループ | ニックネームリストからグループを削除
weechat | nicklist_nick_removing | 0.4.1 | buffer (struct t_gui_buffer *): バッファ parent_group (struct t_gui_nick_group *): 親グループ nick (struct t_gui_nick *): ニックネーム | ニックネームリストからニックネームを削除
weechat | nicklist_group_changed | 0.4.1 | buffer (struct t_gui_buffer *): バッファ parent_group (struct t_gui_nick_group *): 親グループ group (struct t_gui_nick_group *): グループ | ニックネームリストに含まれるグループを変更
weechat | nicklist_nick_changed | 0.4.1 | buffer (struct t_gui_buffer *): バッファ parent_group (struct t_gui_nick_group *): 親グループ nick (struct t_gui_nick *): ニックネーム | ニックネームリストに含まれるニックネームを変更

注記 | (1) xxx は転送で送信するシグナル、yyy は転送元のシグナル。

C 言語での使用例:

    int
    my_hsignal_cb (const void *pointer, void *data, const char *signal,
                   struct t_hashtable *hashtable)
    {
        /* ... */
        return WEECHAT_RC_OK;
    }

    struct t_hook *my_hsignal_hook = weechat_hook_hsignal ("test",
                                                           &my_hsignal_cb, NULL, NULL);

スクリプト (Python) での使用例:

    # プロトタイプ
    def hook_hsignal(signal: str, callback: str, callback_data: str) -> str: ...

    # 例
    def my_hsignal_cb(data: str, signal: str, hashtable: Dict[str, str]) -> int:
        # ...
        return weechat.WEECHAT_RC_OK

    hook = weechat.hook_hsignal("test", "my_hsignal_cb", "")

#### hook_hsignal_send

WeeChat バージョン 0.3.4 以上で利用可、バージョン 1.0, 4.5.0 で更新。

hsignal (ハッシュテーブルを持つシグナル) を送信。

プロトタイプ:

    int weechat_hook_hsignal_send (const char *signal, struct t_hashtable *hashtable);

引数:

- signal: 送信するシグナル; flags are allowed before the signal name (see function hook_signal_send) (WeeChat ≥ 4.5.0)

- hashtable: ハッシュテーブル

戻り値 (WeeChat バージョン 1.0 以上で利用可):

- 最後に実行したコールバックの戻り値 (コールバックを実行しなかった場合は WEECHAT_RC_OK):

  - WEECHAT_RC_OK

  - WEECHAT_RC_OK_EAT

  - WEECHAT_RC_ERROR

C 言語での使用例:

    int rc, rc2;
    struct t_hashtable *hashtable = weechat_hashtable_new (8,
                                                           WEECHAT_HASHTABLE_STRING,
                                                           WEECHAT_HASHTABLE_STRING,
                                                           NULL,
                                                           NULL);
    if (hashtable)
    {
        weechat_hashtable_set (hashtable, "key", "value");
        rc = weechat_hook_hsignal_send ("my_hsignal", hashtable);
        rc2 = weechat_hook_hsignal_send ("[flags:stop_on_error,ignore_eat]my_hsignal2", hashtable);
        weechat_hashtable_free (hashtable);
    }

スクリプト (Python) での使用例:

    # プロトタイプ
    def hook_hsignal_send(signal: str, hashtable: Dict[str, str]) -> int: ...

    # 例
    rc = weechat.hook_hsignal_send("my_hsignal", {"key": "value"})
    rc2 = weechat.hook_hsignal_send("[flags:stop_on_error,ignore_eat]my_hsignal2", {"key": "value"})

##### Hsignal irc_redirect_command

WeeChat バージョン 0.3.4 以上で利用可。

hsignal "irc_redirect_command" は irc コマンドの出力をコールバックに転送するためのものです。

引数は以下のエントリを持つハッシュテーブル (キーと値は文字列) です:

- server: 内部サーバ名 (必須)

- pattern: 転送パターン (必須)、デフォルトパターン (irc プラグインが定義したもの) またはユーザ定義パターン (Hsignal irc_redirect_pattern を参照) のどちらか一方、デフォルトパターンは以下:

  - ison

  - list

  - mode_channel

  - mode_channel_ban ("mode #channel b")

  - mode_channel_ban_exception ("mode #channel e")

  - mode_channel_invite ("mode #channel I")

  - mode_user

  - monitor

  - names

  - ping

  - time

  - topic

  - userhost

  - who

  - whois

  - whowas

- signal: シグナル名 (必須)

- count: 転送を行う回数 (任意、デフォルトは 1 回)

- string: 受信する irc メッセージに含まれる文字列 (任意ですが推奨します、この文字列を含むメッセージだけを転送します)

- timeout: 転送のタイムアウト、秒単位 (任意、デフォルトは 60)

- cmd_filter: フィルタする irc コマンドのコンマ区切りリスト (これらのコマンドはコールバックに送信されます、これ以外のコマンドは無視されます) (任意)

この hsignal を送信したら必ずその直後に irc サーバにコマンドを送信してください、そうすれば送信したコマンドに対する応答が転送されます。

コマンドに対する応答を完全に受信したら、hsignal が送信されます。この hsignal は irc_redirection_xxx_yyy という名前で、ここで xxx は signal、yyy は pattern で指定したものになります。

以下の内容からなるハッシュテーブルが hsignal で送信されます (キーと値は文字列):

- output: コマンドの出力 (メッセージは "\n" で区切られています)

- output_size: output のバイト数 (文字列)

- error: エラー文字列 (エラーが起きた場合):

  - timeout: タイムアウトで転送を中止

- server: 内部サーバ名

- pattern: 転送パターン

- signal: シグナル名

- command: リダイレクトされたコマンド

C 言語での使用例:

    int
    test_whois_cb (const void *pointer, void *data, const char *signal,
                   struct t_hashtable *hashtable)
    {
        weechat_printf (NULL, "error = %s", weechat_hashtable_get (hashtable, "error"));
        weechat_printf (NULL, "output = %s", weechat_hashtable_get (hashtable, "output"));
        return WEECHAT_RC_OK;
    }

    weechat_hook_hsignal ("irc_redirection_test_whois", &test_whois_cb, NULL, NULL);
    struct t_hashtable *hashtable = weechat_hashtable_new (8,
                                                           WEECHAT_HASHTABLE_STRING,
                                                           WEECHAT_HASHTABLE_STRING,
                                                           NULL,
                                                           NULL);
    if (hashtable)
    {
        weechat_hashtable_set (hashtable, "server", "libera");
        weechat_hashtable_set (hashtable, "pattern", "whois");
        weechat_hashtable_set (hashtable, "signal", "test");
        weechat_hashtable_set (hashtable, "string", "FlashCode");
        weechat_hook_hsignal_send ("irc_redirect_command", hashtable);
        weechat_hook_signal_send ("irc_input_send", WEECHAT_HOOK_SIGNAL_STRING,
                                  "libera;;2;;/whois FlashCode");
        weechat_hashtable_free (hashtable);
    }

スクリプト (Python) での使用例:

    def test_whois_cb(data: str, signal: str, hashtable: Dict[str, str]) -> int:
        weechat.prnt("", "error = %s" % hashtable["error"])
        weechat.prnt("", "output = %s" % hashtable["output"])
        return weechat.WEECHAT_RC_OK

    weechat.hook_hsignal("irc_redirection_test_whois", "test_whois_cb", "")
    weechat.hook_hsignal_send("irc_redirect_command",
                              {"server": "libera", "pattern": "whois", "signal": "test",
                               "string": "FlashCode"})
    weechat.hook_signal_send("irc_input_send", weechat.WEECHAT_HOOK_SIGNAL_STRING,
                             "libera;;2;;/whois FlashCode")

##### Hsignal irc_redirect_pattern

WeeChat バージョン 0.3.4 以上で利用可。

hsignal "irc_redirect_pattern" は irc 転送用のパターンを作成するために送信します (Hsignal irc_redirect_command を参照)。

引数は以下のエントリを持つハッシュテーブルです (キーと値は文字列):

- pattern: パターンの名前 (必須)

- timeout: パターンのデフォルトタイムアウト、秒単位 (任意、デフォルトは 60)

- cmd_start: 転送を開始するコマンドのコンマ区切りリスト (任意)

- cmd_stop: 転送を終了するコマンドのコンマ区切りリスト (必須)

- cmd_extra: コマンドを停止した後に受信する可能性のあるコマンドのコンマ区切りリスト (任意)

cmd_start、cmd_stop、cmd_extra には受け取ったメッセージに必ず含まれていなければいけない "string" の位置を示す整数を与えることが可能、例:

    352:1,354,401:1

コマンド 352 と 401 の応答は最初の受信メッセージの第 1 引数に "string" が含まれていなければいけません。

重要 | パターンは転送で使われた後に破棄されます、複数回の転送でパターンを必要な場合は、転送前に毎回必ずパターンを作ってください。

C 言語での使用例:

    struct t_hashtable *hashtable = weechat_hashtable_new (8,
                                                           WEECHAT_HASHTABLE_STRING,
                                                           WEECHAT_HASHTABLE_STRING,
                                                           NULL,
                                                           NULL);
    if (hashtable)
    {
        weechat_hashtable_set (hashtable, "pattern", "my_whois");
        weechat_hashtable_set (hashtable, "timeout", "30");
        weechat_hashtable_set (hashtable, "cmd_start", "311:1");
        weechat_hashtable_set (hashtable, "cmd_stop", "318:1,401:1,402:1,431:1,461");
        weechat_hashtable_set (hashtable, "cmd_extra", "318:1");
        weechat_hook_hsignal_send ("irc_redirect_pattern", hashtable);
        /*
         * now redirect irc whois command with hsignal irc_redirect_command,
         * using pattern "my_whois"
         */
        /* ... */
        weechat_hashtable_free (hashtable);
    }

スクリプト (Python) での使用例:

    weechat.hook_hsignal_send("irc_redirect_pattern",
                              {"pattern": "my_whois", "timeout": "30",
                               "cmd_start": "311:1",
                               "cmd_stop": "318:1,401:1,402:1,431:1,461",
                               "cmd_extra": "318:1"})
    # now redirect irc whois command with hsignal irc_redirect_command
    # using pattern "my_whois"
    # ...

#### hook_config

WeeChat バージョン 1.5 で更新。

設定オプションをフック。

プロトタイプ:

    struct t_hook *weechat_hook_config (const char *option,
                                        int (*callback)(const void *pointer,
                                                        void *data,
                                                        const char *option,
                                                        const char *value),
                                        const void *callback_pointer,
                                        void *callback_data);

引数:

- option: オプション、書式は完全な名前、コマンド `/set` で使うのと同じ (例: `weechat.look.item_time_format`)、ワイルドカード `*` を使うことができます (a priority is allowed before the option, see note about priority)

- callback: 設定オプションが変更されたら呼び出すコールバック関数、引数と戻り値:

  - const void *pointer: ポインタ

  - void *data: ポインタ

  - const char *option: オプションの名前

  - const char *value: オプションの新しい値

  - 戻り値:

    - WEECHAT_RC_OK

    - WEECHAT_RC_ERROR

- callback_pointer: WeeChat が callback コールバックを呼び出す際にコールバックに渡すポインタ

- callback_data: WeeChat が callback コールバックを呼び出す際にコールバックに渡すポインタ; このポインタが NULL でない場合、このポインタは malloc (または類似の関数) によって割り当てられたものでなければいけません。さらに、このポインタはここで作成したフックが削除された時点で自動的に開放されます

戻り値:

- 新しいフックへのポインタ、エラーが起きた場合は NULL

C 言語での使用例:

    int
    my_config_cb (const void *pointer, void *data, const char *option,
                  const char *value)
    {
        /* ... */
        return WEECHAT_RC_OK;
    }

    /* catch changes to option "weechat.look.item_time_format" */
    struct t_hook *my_config_hook = weechat_hook_config ("weechat.look.item_time_format",
                                                         &my_config_cb, NULL, NULL);

スクリプト (Python) での使用例:

    # プロトタイプ
    def hook_config(option: str, callback: str, callback_data: str) -> str: ...

    # 例
    def my_config_cb(data: str, option: str, value: str) -> int:
        # ...
        return weechat.WEECHAT_RC_OK

    # catch changes to option "weechat.look.item_time_format"
    hook = weechat.hook_config("weechat.look.item_time_format", "my_config_cb", "")

#### hook_modifier

WeeChat バージョン 1.5 で更新。

修飾子をフック。

プロトタイプ:

    struct t_hook *weechat_hook_modifier (const char *modifier,
                                          char *(*callback)(const void *pointer,
                                                            void *data,
                                                            const char *modifier,
                                                            const char *modifier_data,
                                                            const char *string),
                                          const void *callback_pointer,
                                          void *callback_data);

引数:

- modifier: modifier name (a priority is allowed before the modifier, see note about priority) (以下の表を参照)

- callback: 修飾子が使われた際に呼び出すコールバック関数、引数と戻り値:

  - const void *pointer: ポインタ

  - void *data: ポインタ

  - const char *modifier: 修飾子の名前

  - const char *modifier_data: 修飾子に渡すデータ

  - const char *string: 修飾子に渡す文字列

  - 戻り値: 新しい文字列

- callback_pointer: WeeChat が callback コールバックを呼び出す際にコールバックに渡すポインタ

- callback_data: WeeChat が callback コールバックを呼び出す際にコールバックに渡すポインタ; このポインタが NULL でない場合、このポインタは malloc (または類似の関数) によって割り当てられたものでなければいけません。さらに、このポインタはここで作成したフックが削除された時点で自動的に開放されます

戻り値:

- 新しいフックへのポインタ、エラーが起きた場合は NULL

WeeChat とプラグインが使う修飾子のリスト:

修飾子 | Min WeeChat | 修飾子データ | 文字列 | 出力
--- | --- | --- | --- | ---
irc_batch | 4.0.0 | Server name + "," + batch type + "," + batch parameters | Content of multiple messages, separated by a newline char ("\n"). | New content of messages (number can be different), an empty string discards all messages in the batch.
irc_cap_sync_req | 4.0.0 | Server name + "," + supported capabilities on server (separated by spaces) | Capabilities to request (separated by spaces). | New content of capabilities to request (separated by spaces).
irc_in_xxx (1) |  | サーバ名 | IRC サーバから受信したメッセージの内容 (文字セットをデコードする前) Warning: the string may contain invalid UTF-8 data; use only for raw operations on a message. Modifier irc_in2_xxx is recommended instead. | メッセージの新しい内容
irc_in2_xxx (1) | 0.3.5 | サーバ名 | IRC サーバから受信したメッセージの内容 (文字セットをデコードした後) | メッセージの新しい内容
irc_out1_xxx (1) | 0.3.7 | サーバ名 | IRC サーバに送信するメッセージの内容 (自動分割前、自動分割はデフォルトでメッセージを 512 バイト内に収まるように分割します)。 | メッセージの新しい内容
irc_out_xxx (1) |  | サーバ名 | IRC サーバに送信するメッセージの内容 (自動分割後、自動分割はデフォルトでメッセージを 512 バイト内に収まるように分割します)。 | メッセージの新しい内容
relay_client_irc_in | 4.0.0 | String with relay client pointer (eg: "0x1234abcd") | Content of message received from relay IRC client. | New content of message.
relay_client_irc_out1 | 4.0.0 | String with relay client pointer (eg: "0x1234abcd") | Content of message about to be sent to relay IRC client before automatic split (to fit in 512 bytes by default). | New content of message.
relay_client_irc_out | 4.0.0 | String with relay client pointer (eg: "0x1234abcd") | Content of message about to be sent to relay IRC client after automatic split (to fit in 512 bytes by default). | New content of message.
bar_condition_yyy (2) |  | ウィンドウへのポインタの文字列 (eg: "0x1234abcd") | 空文字列 | バーを表示する場合は "1"、隠す場合は "0"
history_add | 0.3.2 | バッファへのポインタの文字列 (eg: "0x1234abcd") | コマンド履歴に追加するコマンドラインの内容 (バッファとグローバル履歴) | コマンド履歴に追加した文字列
input_text_content |  | バッファへのポインタの文字列 (eg: "0x1234abcd") | コマンドラインの内容 | コマンドラインの新しい内容
input_text_display |  | バッファへのポインタの文字列 (eg: "0x1234abcd") | カーソルタグを含まないコマンドラインの内容 | 新しい文字列、表示のみ (コマンドラインは変化しない)
input_text_display_with_cursor |  | バッファへのポインタの文字列 (eg: "0x1234abcd") | カーソルタグを含むコマンドラインの内容 | 新しい文字列、表示のみ (コマンドラインは変化しない)
input_text_for_buffer | 0.3.7 | バッファへのポインタの文字列 (eg: "0x1234abcd") | バッファに送信するコマンドラインの内容 (テキストまたはコマンド) | バッファに送信するコマンドラインの新しい内容
weechat_print |  | buffer pointer (eg: "0x1234abcd") + ";" + tags (3) | 表示されたメッセージ | 表示される新しいメッセージ 行が表示される際に呼び出されるフックについての詳細は hook_line を参照してください

注記 | (1) xxx は IRC コマンド名。 (2) yyy はバーの名前。 (3) With WeeChat ≤ 2.8, the format was: plugin + ";" + buffer_name + ";" + tags.

C 言語での使用例:

    char *
    my_modifier_cb (const void *pointer, void *data, const char *modifier,
                    const char *modifier_data,
                    const char *string)
    {
        char *result;
        int length;

        if (!string)
            return NULL;

        length = strlen (string) + 5;
        result = malloc (length);
        if (result)
        {
            /* add "xxx" to any message printed */
            snprintf (result, length, "%s xxx", string);
        }

        return result;
    }

    struct t_hook *my_modifier_hook = weechat_hook_modifier ("weechat_print",
                                                             &my_modifier_cb, NULL, NULL);

スクリプト (Python) での使用例:

    # プロトタイプ
    def hook_modifier(modifier: str, callback: str, callback_data: str) -> str: ...

    # 例
    def my_modifier_cb(data: str, modifier: str, modifier_data: str, string: str) -> str:
        return "%s xxx" % string

    hook = weechat.hook_modifier("weechat_print", "my_modifier_cb", "")

#### hook_modifier_exec

修飾子を実行。

プロトタイプ:

    char *weechat_hook_modifier_exec (const char *modifier,
                                      const char *modifier_data,
                                      const char *string);

引数:

- modifier: 修飾子の名前

- modifier_data: 修飾子に渡すデータ

- string: 修正する文字列

戻り値:

- 修正された文字列、エラーが起きた場合は NULL

WeeChat とプラグインが定義する修飾子のリスト:

修飾子 | Min WeeChat | 修飾子データ | 文字列 | 出力
--- | --- | --- | --- | ---
charset_decode |  | plugin.buffer_name | 任意の文字列 | プラグインおよびバッファの文字セットから UTF-8 にデコードされた文字列
charset_encode |  | plugin.buffer_name | 任意の文字列 | UTF-8 からプラグインおよびバッファの文字セットにエンコードされた文字列
irc_color_decode |  | 色を保持する場合は "1"、削除する場合は "0" | 任意の文字列 | WeeChat 色コードに変換された IRC 色コードを含む (または IRC 色コードを削除された) 文字列
irc_color_encode |  | 色を保持する場合は "1"、削除する場合は "0" | 任意の文字列 | IRC 色コードを含む (または IRC 色コードを削除された) 文字列
irc_color_decode_ansi | 1.0 | 色を保持する場合は "1"、削除する場合は "0" | 任意の文字列 | IRC 色コードに変換された ANSI 色コードを含む (または ANSI 色コードを削除された) 文字列
irc_command_auth | 0.4.1 | サーバ名 | 認証コマンド (例: `/msg nickserv identify password`) | パスワードを隠したコマンド (例: `/msg nickserv identify ********`)
irc_message_auth | 0.4.1 | サーバ名 | `/msg` をサーバに送信した後に表示されるメッセージ | パスワードを隠したメッセージ
irc_tag_escape_value | 3.3 | - | Any string. | String with IRC tag value escaped, see this page ↗.
irc_tag_unescape_value | 3.3 | - | Any string. | String with IRC tag value unescaped, see this page ↗.
color_decode | 4.3.0 | Replacement string for colors removed | Any string. | String with WeeChat colors converted to a replacement string (colors stripped if the replacement string is empty).
color_decode_ansi | 1.0 | 色を保持する場合は "1"、削除する場合は "0" | 任意の文字列 | WeeChat 色コードに変換された ANSI 色コードを含む (または ANSI 色コードを削除された) 文字列
color_encode_ansi | 2.7 | - | 任意の文字列 | String with WeeChat colors converted to ANSI colors.
eval_path_home | 2.7 | Optional: `directory=xxx` where `xxx` can be: `config`, `data`, `cache`, `runtime` | Any string. | Evaluated path, result of the function string_eval_path_home.

C 言語での使用例:

    char *new_string = weechat_hook_modifier_exec ("my_modifier",
                                                   my_data, my_string);

スクリプト (Python) での使用例:

    # プロトタイプ
    def hook_modifier_exec(modifier: str, modifier_data: str, string: str) -> str: ...

    # 例
    weechat.hook_modifier_exec("my_modifier", my_data, my_string)

#### hook_info

WeeChat バージョン 1.5, 2.5 で更新。

インフォをフック (コールバックを呼び出し、文字列を返す)。

プロトタイプ:

    struct t_hook *weechat_hook_info (const char *info_name,
                                      const char *description,
                                      const char *args_description,
                                      char *(*callback)(const void *pointer,
                                                        void *data,
                                                        const char *info_name,
                                                        const char *arguments),
                                      const void *callback_pointer,
                                      void *callback_data);

引数:

- info_name: インフォの名前 (a priority is allowed before the info name, see note about priority)

- description: 説明

- args_description: 引数の説明 (任意、NULL にすることも可)

- callback: インフォが要求されたら呼び出すコールバック関数、引数と戻り値:

  - const void *pointer: ポインタ

  - void *data: ポインタ

  - const char *info_name: インフォの名前

  - const char *arguments: 追加の引数、インフォに依存

  - 戻り値: 要求されたインフォの値

- callback_pointer: WeeChat が callback コールバックを呼び出す際にコールバックに渡すポインタ

- callback_data: WeeChat が callback コールバックを呼び出す際にコールバックに渡すポインタ; このポインタが NULL でない場合、このポインタは malloc (または類似の関数) によって割り当てられたものでなければいけません。さらに、このポインタはここで作成したフックが削除された時点で自動的に開放されます

戻り値:

- 新しいフックへのポインタ、エラーが起きた場合は NULL

注記 | WeeChat バージョン 2.5 以上の場合、コールバックは確保された文字列を返します (WeeChat バージョン 2.4 以下の場合、コールバックは定数文字列へのポインタを返します)。

C 言語での使用例:

    char *
    my_info_cb (const void *pointer, void *data, const char *info_name,
                const char *arguments)
    {
        /* ... */
        return strdup ("some_info");
    }

    /* add info "my_info" */
    struct t_hook *my_info_hook = weechat_hook_info ("my_info",
                                                     "Some info",
                                                     "Info about arguments",
                                                     &my_info_cb, NULL, NULL);

スクリプト (Python) での使用例:

    # プロトタイプ
    def hook_info(info_name: str, description: str, args_description: str,
                  callback: str, callback_data: str) -> str: ...

    # 例
    def my_info_cb(data: str, info_name: str, arguments: str) -> str:
        return "some_info"

    hook = weechat.hook_info("my_info", "Some info", "Info about arguments",
                             "my_info_cb", "")

#### hook_info_hashtable

WeeChat バージョン 0.3.4 以上で利用可、バージョン 1.5 で更新。

インフォをフック (コールバックを呼び出し、ハッシュテーブルを返す)。

プロトタイプ:

    struct t_hook *weechat_hook_info_hashtable (const char *info_name,
                                                const char *description,
                                                const char *args_description,
                                                const char *output_description,
                                                struct t_hashtable *(*callback)(const void *pointer,
                                                                                void *data,
                                                                                const char *info_name,
                                                                                struct t_hashtable *hashtable),
                                                const void *callback_pointer,
                                                void *callback_data);

引数:

- info_name: インフォの名前 (a priority is allowed before the info name, see note about priority)

- description: 説明

- args_description: 引数ハッシュテーブルの説明 (任意、NULL でも可)

- output_description: コールバックが返すハッシュテーブルの説明 (任意、NULL でも可)

- callback: インフォを要求する際に呼び出すコールバック関数、引数と戻り値:

  - const void *pointer: ポインタ

  - void *data: ポインタ

  - const char *info_name: インフォの名前

  - struct t_hashtable *hashtable: ハッシュテーブル、インフォに依存

  - 戻り値: 要求したハッシュテーブル

- callback_pointer: WeeChat が callback コールバックを呼び出す際にコールバックに渡すポインタ

- callback_data: WeeChat が callback コールバックを呼び出す際にコールバックに渡すポインタ; このポインタが NULL でない場合、このポインタは malloc (または類似の関数) によって割り当てられたものでなければいけません。さらに、このポインタはここで作成したフックが削除された時点で自動的に開放されます

戻り値:

- 新しいフックへのポインタ、エラーが起きた場合は NULL

C 言語での使用例:

    struct t_hashtable *
    my_info_hashtable_cb (const void *pointer, void *data, const char *info_name,
                          struct t_hashtable *hashtable)
    {
        /* ... */
        return pointer_to_new_hashtable;
    }

    /* add info "my_info_hashtable" */
    struct t_hook *my_info_hook = weechat_hook_info_hashtable ("my_info_hashtable",
                                                               "Some info",
                                                               "Info about input hashtable",
                                                               "Info about output hashtable",
                                                               &my_info_hashtable_cb, NULL, NULL);

スクリプト (Python) での使用例:

    # プロトタイプ
    def hook_info_hashtable(info_name: str, description: str, args_description: str,
                            output_description: str, callback: str, callback_data: str) -> str: ...

    # 例
    def my_info_hashtable_cb(data: str, info_name: str, hashtable: Dict[str, str]) -> Dict[str, str]:
        return {"test_key": "test_value"}

    hook = weechat.hook_info_hashtable("my_info_hashtable", "Some info",
                                       "Info about input hashtable",
                                       "Info about output hashtable",
                                       "my_info_hashtable_cb", "")

#### hook_infolist

WeeChat バージョン 1.5 で更新。

インフォリストをフック: コールバックは要求したインフォリストへのポインタを返す。

プロトタイプ:

    struct t_hook *weechat_hook_infolist (const char *infolist_name,
                                          const char *description,
                                          const char *pointer_description,
                                          const char *args_description,
                                          struct t_infolist *(*callback)(const void *pointer,
                                                                         void *data,
                                                                         const char *infolist_name,
                                                                         void *obj_pointer,
                                                                         const char *arguments),
                                          const void *callback_pointer,
                                          void *callback_data);

引数:

- infolist_name: インフォリストの名前 (a priority is allowed before the infolist name, see note about priority)

- description: 説明

- pointer_description: ポインタの説明 (任意、NULL でも可)

- args_description: 引数の説明 (任意、NULL でも可)

- callback: インフォリストが要求された際に呼び出すコールバック関数、引数と戻り値:

  - const void *pointer: ポインタ

  - void *data: ポインタ

  - const char *infolist_name: インフォリストの名前

  - void *pointer: インフォリストが返すオブジェクトへのポインタ (インフォリストの要素を 1 つだけ返す)

  - const char *arguments: 追加の引数、インフォリストに依存

  - 戻り値: 要求したインフォリスト

- callback_pointer: WeeChat が callback コールバックを呼び出す際にコールバックに渡すポインタ

- callback_data: WeeChat が callback コールバックを呼び出す際にコールバックに渡すポインタ; このポインタが NULL でない場合、このポインタは malloc (または類似の関数) によって割り当てられたものでなければいけません。さらに、このポインタはここで作成したフックが削除された時点で自動的に開放されます

戻り値:

- 新しいフックへのポインタ、エラーが起きた場合は NULL

C 言語での使用例:

    struct t_infolist *
    my_infolist_cb (const void *pointer, void *data, const char *infolist_name,
                    void *obj_pointer, const char *arguments)
    {
        struct t_infolist *my_infolist;

        /* インフォリストを作成 */
        /* ... */

        return my_infolist;
    }

    /* インフォリスト "my_infolist" を追加 */
    struct t_hook *my_infolist = weechat_hook_infolist ("my_infolist",
                                                        "Infolist with some data",
                                                        "Info about pointer",
                                                        "Info about arguments",
                                                        &my_infolist_cb, NULL, NULL);

スクリプト (Python) での使用例:

    # プロトタイプ
    def hook_infolist(infolist_name: str, description: str, pointer_description: str,
                      args_description: str, callback: str, callback_data: str) -> str: ...

    # 例
    def my_infolist_cb(data: str, infolist_name: str, pointer: str, arguments: str) -> str:
        # build infolist
        # ...
        return my_infolist

    hook = weechat.hook_infolist("my_infolist", "Infolist with some data",
                                 "Info about pointer", "Info about arguments",
                                 "my_infolist_cb", "")

#### hook_hdata

WeeChat バージョン 1.5 で更新。

hdata をフック: コールバックは要求した hdata へのポインタを返す。

プロトタイプ:

    struct t_hook *weechat_hook_hdata (const char *hdata_name,
                                       const char *description,
                                       struct t_hdata *(*callback)(const void *pointer,
                                                                   void *data,
                                                                   const char *hdata_name),
                                       const void *callback_pointer,
                                       void *callback_data);

引数:

- hdata_name: hdata の名前 (a priority is allowed before the hdata name, see note about priority)

- description: 説明

- callback: hdata が要求された際に呼び出すコールバック関数、引数と戻り値:

  - const void *pointer: ポインタ

  - void *data: ポインタ

  - const char *hdata_name: hdata の名前

  - 戻り値: 要求された hdata

- callback_pointer: WeeChat が callback コールバックを呼び出す際にコールバックに渡すポインタ

- callback_data: WeeChat が callback コールバックを呼び出す際にコールバックに渡すポインタ; このポインタが NULL でない場合、このポインタは malloc (または類似の関数) によって割り当てられたものでなければいけません。さらに、このポインタはここで作成したフックが削除された時点で自動的に開放されます

戻り値:

- 新しいフックへのポインタ、エラーが起きた場合は NULL

C 言語での使用例:

    struct t_hdata *
    my_hdata_cb (const void *pointer, void *data, const char *hdata_name)
    {
        struct t_hdata *my_hdata;

        /* build hdata */
        /* ... */

        return my_hdata;
    }

    /* add hdata "my_hdata" */
    struct t_hook *my_hdata = weechat_hook_hdata ("my_hdata",
                                                  "Hdata for my structure",
                                                  &my_hdata_cb, NULL, NULL);

注記 | スクリプト API ではこの関数を利用できません。

#### hook_focus

WeeChat バージョン 1.5, 4.0.0, 4.1.0 で更新。

フォーカス (マウスイベントやカーソルモード (カーソルが自由に移動出来る状態) でキーが押されたこと) をフック。

プロトタイプ:

    struct t_hook *weechat_hook_focus (const char *area,
                                       struct t_hashtable *(*callback)(const void *pointer,
                                                                       void *data,
                                                                       struct t_hashtable *info),
                                       const void *callback_pointer,
                                       void *callback_data);

引数:

- area: チャットエリアの場合は "chat"、またはバー要素の名前 (a priority is allowed before the area, see note about priority)

- callback: フォーカスが当たったら呼び出すコールバック関数、引数と戻り値:

  - const void *pointer: ポインタ

  - void *data: ポインタ

  - struct t_hashtable *info: フォーカスの情報を含むハッシュテーブルと、他の (より高い優先度を持つ) フォーカスコールバックを呼び出して返された文字列 (以下のテーブルを参照)

  - 戻り値: "info" ポインタ (完全なハッシュテーブル) または新しいハッシュテーブル (コールバックが作成、キーと値は "string" 型) へのポインタ、この新しいハッシュテーブルの内容は info に追加され、他のフォーカスコールバックに渡されます

- callback_pointer: WeeChat が callback コールバックを呼び出す際にコールバックに渡すポインタ

- callback_data: WeeChat が callback コールバックを呼び出す際にコールバックに渡すポインタ; このポインタが NULL でない場合、このポインタは malloc (または類似の関数) によって割り当てられたものでなければいけません。さらに、このポインタはここで作成したフックが削除された時点で自動的に開放されます

重要 | マウスジェスチャの場合、コールバックを 2 回呼び出します: 1 回目はボタンが押された時 (この時のエリアはジェスチャ対象のエリアです)、2 回目はボタンが離された時 (この時のエリアはマスジェスチャを開始したエリアとは異なる場合があります): このため、必ず 毎回 コールバックをテストして、ハッシュテーブルに含まれる info を使う前にエリアが一致していることを確認して下さい。

コールバックに送られるハッシュテーブルの内容 (キーと値は "string" 型):

キー (1) | 説明 | 値の例 | 定義できない場合の値
--- | --- | --- | ---
_x | 画面上での列座標 | "0" …​ "n" |
_y | 画面上での行座標 | "0" …​ "n" |
_key | キーまたはマウスイベント | "button1"、"button2-gesture-left"、…​ |
_window | ウィンドウへのポインタ | "0x1234abcd" | ""
_window_number | ウィンドウの番号 | "1" …​ "n" | "*"
_buffer | バッファへのポインタ | "0x1234abcd" | ""
_buffer_number | バッファの番号 | "1" …​ "n" | "-1"
_buffer_plugin | バッファのプラグイン名 | "core"、"irc"、…​ | ""
_buffer_name | バッファの名前 | "weechat"、"libera.#weechat"、…​ | ""
_buffer_full_name | バッファの完全な名前 | "core.weechat"、"irc.libera.#weechat"、…​ | ""
_buffer_localvar_XXX (2) | バッファのローカル変数 | 任意の値 | 未定義
_chat | チャットエリアインジケータ | "0" または "1" | "0"
_chat_line | 行へのポインタ (WeeChat バージョン 1.2 以上で利用可) | "0x1234abcd" | ""
_chat_line_x | 行中の列番号 (3) | "0" …​ "n" | "-1"
_chat_line_y | 行番号 (3) | "0" …​ "n" | "-1"
_chat_line_date | 日付/時間の行 | "1313237175" | "0"
_chat_line_date_usec | Microseconds of line date/time. | "123456" | "0"
_chat_line_date_printed | 日付/時間の行 (4) | "1313237175" | "0"
_chat_line_date_usec_printed | Microseconds of line printed date/time (4). | "123456" | "0"
_chat_line_time | 表示された時間 | "14:06:15" | ""
_chat_line_tags | 行に設定されたタグ | "irc_privmsg,nick_flashy,log1" | ""
_chat_line_nick | 行を発言したニックネーム | "FlashCode" | ""
_chat_line_prefix | 行のプレフィックス | "@FlashCode" | ""
_chat_line_message | 行のメッセージ部分 | "Hello world!" | ""
_chat_focused_line | Line at (x, y) (WeeChat ≥ 4.0.0). | "Hello world!" | ""
_chat_focused_line_bol | Text from beginning of line to (x-1, y) (WeeChat ≥ 4.1.0). | "Hello" | ""
_chat_focused_line_eol | Text from (x, y) to end of line (WeeChat ≥ 4.1.0). | "llo world!" | ""
_chat_word | (x,y) の位置にある単語 | "Hello" | ""
_chat_bol | Text from beginning of message to (x-1, y). | "He" | ""
_chat_eol | Text from (x, y) to the end of message. | "llo world!" | ""
_bar_name | バーの名前 | "title"、"nicklist"、…​ | ""
_bar_filling | バーのフィリング | "horizontal"、"vertical"、…​ | ""
_bar_item_name | バー要素の名前 | "buffer_nicklist"、"hotlist"、…​ | ""
_bar_item_line | バー要素中の行座標 | "0" …​ "n" | "-1"
_bar_item_col | バー要素中の列座標 | "0" …​ "n" | "-1"
_bar_window | Pointer to bar window (WeeChat ≥ 2.9). | "0x1234abcd" | ""

注記 | (1) "2" を後ろにつけたキー (例: "_x2"、"_y2"、"_window2"、…​) には 2 番目の位置に関する情報が収められています (この値に意味があるマウスジェスチャの時だけで、マウスボタンの離された位置に関する情報が収められています)。 (2) `XXX` はバッファのローカル変数の名前です。 (3) これは自由内容のバッファで定義されています。 (4) WeeChat がバッファに行を追加した日付です ("_chat_line_date" よりも大きいか同じ)。

バー要素 "buffer_nicklist" の追加情報:

プラグイン (1) | キー | 説明
--- | --- | ---
weechat | nick | ニックネーム
weechat | prefix | ニックネームのプレフィックス
weechat | group | グループ名
irc | irc_nick | Pointer to IRC nick (WeeChat ≥ 3.0).
irc | irc_host | ニックネームのホスト名 (判る場合)

注記 | (1) プラグインの名前は hook_focus がどのバー要素に関する情報を渡したかを意味しています (したがって、例えばプラグインが "irc" の場合、ハッシュテーブル info の内容は irc バッファに関するものになります)。

戻り値:

- 新しいフックへのポインタ、エラーが起きた場合は NULL

C 言語での使用例:

    struct t_hashtable *
    my_focus_nicklist_cb (const void *pointer, void *data, struct t_hashtable *info)
    {
        /* add strings in hashtable */
        /* ... */

        return info;
    }

    /* add focus on nicklist */
    struct t_hook *my_focus = weechat_hook_focus ("buffer_nicklist",
                                                  &my_focus_nicklist_cb, NULL, NULL);

スクリプト (Python) での使用例:

    # プロトタイプ
    def hook_focus(area: str, callback: str, callback_data: str) -> str: ...

    # 例
    def my_focus_nicklist_cb(data: str, info: Dict[str, str]) -> Dict[str, str]:
        # build dict
        # ...
        return my_dict

    hook = weechat.hook_focus("buffer_nicklist", "my_focus_nicklist_cb", "")

#### hook_set

WeeChat バージョン 0.3.9 以上で利用可 (スクリプト: WeeChat バージョン 0.4.3 以上で利用可)。

フックプロパティの文字列値を設定。

プロトタイプ:

    void weechat_hook_set (struct t_hook *hook, const char *property,
                           const char *value);

引数:

- hook: "weechat_hook_xxx()" の戻り値

- property: プロパティ名 (以下の表を参照)

- value: プロパティの新しい値

プロパティ:

名前 | Min WeeChat | フック型 | 値 | 説明
--- | --- | --- | --- | ---
subplugin |  | 任意の型 | 任意の文字列 | サブプラグインの名前 (通常は `/help command` で command をタイプした時のフックで表示されるスクリプト名)
keep_spaces_right | 4.6.0 | command, command_run | "0" or "1" | Keep trailing spaces in command arguments when it is executed.
stdin | 0.4.3 | process、process_hashtable | 任意の文字列 | 子プロセスの標準入力 (stdin) にデータを送信
stdin_close | 0.4.3 | process、process_hashtable | (非使用) | 子プロセスの標準入力 (stdin) にデータを送信するパイプを閉じる
signal | 1.0 | process、process_hashtable | シグナル番号または以下の名前から 1 つ: `hup`、`int`、`quit`、`kill`、`term`、`usr1`、`usr2` | 子プロセスにシグナルを送信

C 言語での使用例:

    struct t_hook *my_command_hook =
        weechat_hook_command ("abcd", "description",
                              "args", "description args",
                              "", &my_command_cb, NULL, NULL);
    weechat_hook_set (my_command_hook, "subplugin", "test");

スクリプト (Python) での使用例:

    # プロトタイプ
    def hook_set(hook: str, property: str, value: str) -> int: ...

    # 例
    def my_process_cb(data: str, command: str, return_code: int, out: str, err: str) -> int:
        # ...
        return weechat.WEECHAT_RC_OK

    hook = weechat.hook_process_hashtable("/path/to/command", {"stdin": "1"},
                                          20000, "my_process_cb", "")
    weechat.hook_set(hook, "stdin", "data sent to stdin of child process")
    weechat.hook_set(hook, "stdin_close", "")  # optional

#### unhook

フックを解除。

プロトタイプ:

    void weechat_unhook (struct t_hook *hook);

引数:

- hook: "weechat_hook_xxx()" の戻り値

C 言語での使用例:

    struct t_hook *my_hook = weechat_hook_command ( /* ... */ );
    /* ... */
    weechat_unhook (my_hook);

スクリプト (Python) での使用例:

    # プロトタイプ
    def unhook(hook: str) -> int: ...

    # 例
    weechat.unhook(my_hook)

#### unhook_all

WeeChat バージョン 1.5 で更新。

現在のプラグインで設定したフックをすべて解除。

プロトタイプ:

    void weechat_unhook_all (const char *subplugin);

引数:

- subplugin: これが NULL でない場合、ここで指定した "subplugin" を持つフックだけを解除します (スクリプトから API を使う場合にはこの引数を指定できません)

C 言語での使用例:

    weechat_unhook_all (NULL);

スクリプト (Python) での使用例:

    # プロトタイプ
    def unhook_all() -> int: ...

    # 例
    weechat.unhook_all()

### 3.15. バッファ

バッファを作成/検索/閉じる関数

#### buffer_new

WeeChat バージョン 1.5 で更新。

新しいバッファを開く。

注記 | If you want to immediately set buffer properties (buffer type, local variables, key bindings, etc.), then better use the function buffer_new_props which sets these properties during the buffer creation, before sending signal buffer_opened.

プロトタイプ:

    struct t_gui_buffer *weechat_buffer_new (const char *name,
                                             int (*input_callback)(const void *pointer,
                                                                   void *data,
                                                                   struct t_gui_buffer *buffer,
                                                                   const char *input_data),
                                             const void *input_callback_pointer,
                                             void *input_callback_data,
                                             int (*close_callback)(const void *pointer,
                                                                   void *data,
                                                                   struct t_gui_buffer *buffer),
                                             const void *close_callback_pointer,
                                             void *close_callback_data);

引数:

- name: バッファの名前 (プラグインに対して固有)

- input_callback: 入力テキストをバッファに挿入する際に呼び出すコールバック関数、引数と戻り値:

  - const void *pointer: ポインタ

  - void *data: ポインタ

  - struct t_gui_buffer *buffer: バッファポインタ

  - const char *input_data: 入力データ

  - 戻り値:

    - WEECHAT_RC_OK

    - WEECHAT_RC_ERROR

- input_callback_pointer: WeeChat が input_callback コールバックを呼び出す際にコールバックに渡すポインタ

- input_callback_data: WeeChat が input_callback コールバックを呼び出す際にコールバックに渡すポインタ; このポインタが NULL でない場合、このポインタは malloc (または類似の関数) によって割り当てられたものでなければいけません。さらに、このポインタはここで作成したバッファが閉じられた時点で自動的に開放されます

- close_callback: バッファを閉じる際に呼び出すコールバック関数、引数と戻り値:

  - const void *pointer: ポインタ

  - void *data: ポインタ

  - struct t_gui_buffer *buffer: バッファポインタ

  - 戻り値:

    - WEECHAT_RC_OK

    - WEECHAT_RC_ERROR

- close_callback_pointer: WeeChat が close_callback コールバックを呼び出す際にコールバックに渡すポインタ

- close_callback_data: WeeChat が close_callback コールバックを呼び出す際にコールバックに渡すポインタ; このポインタが NULL でない場合、このポインタは malloc (または類似の関数) によって割り当てられたものでなければいけません。さらに、このポインタはここで作成したバッファが閉じられた時点で自動的に開放されます

戻り値:

- 新しいバッファへのポインタ、エラーが起きた場合は NULL

C 言語での使用例:

    int
    my_input_cb (const void *pointer, void *data,
                 struct t_gui_buffer *buffer, const char *input_data)
    {
        weechat_printf (buffer, "Text: %s", input_data);
        return WEECHAT_RC_OK;
    }

    int
    my_close_cb (const void *pointer, void *data, struct t_gui_buffer *buffer)
    {
        weechat_printf (NULL, "Buffer _%s_ will be closed!",
                        weechat_buffer_get_string (buffer, "name"));
        return WEECHAT_RC_OK;
    }

    struct t_gui_buffer *my_buffer = weechat_buffer_new ("my_buffer",
                                                         &my_input_cb, NULL, NULL,
                                                         &my_close_cb, NULL, NULL);

スクリプト (Python) での使用例:

    # プロトタイプ
    def buffer_new(name: str, input_callback: str, input_callback_data: str,
                   close_callback: str, close_callback_data: str) -> str: ...

    # 例
    def my_input_cb(data: str, buffer: str, input_data: str) -> int:
        weechat.prnt(buffer, "Text: %s" % input_data)
        return weechat.WEECHAT_RC_OK

    def my_close_cb(data: str, buffer: str) -> int:
        weechat.prnt("", "Buffer _%s_ will be closed!" % weechat.buffer_get_string(buffer, "name"))
        return weechat.WEECHAT_RC_OK

    buffer = weechat.buffer_new("my_buffer", "my_input_cb", "", "my_close_cb", "")

#### buffer_new_props

WeeChat ≥ 3.5

Open a new buffer and apply properties.

プロトタイプ:

    struct t_gui_buffer *weechat_buffer_new_props (const char *name,
                                                   struct t_hashtable *properties,
                                                   int (*input_callback)(const void *pointer,
                                                                         void *data,
                                                                         struct t_gui_buffer *buffer,
                                                                         const char *input_data),
                                                   const void *input_callback_pointer,
                                                   void *input_callback_data,
                                                   int (*close_callback)(const void *pointer,
                                                                         void *data,
                                                                         struct t_gui_buffer *buffer),
                                                   const void *close_callback_pointer,
                                                   void *close_callback_data);

引数:

- name: バッファの名前 (プラグインに対して固有)

- properties: properties to apply (see function buffer_set for the allowed properties)

- input_callback: 入力テキストをバッファに挿入する際に呼び出すコールバック関数、引数と戻り値:

  - const void *pointer: ポインタ

  - void *data: ポインタ

  - struct t_gui_buffer *buffer: バッファポインタ

  - const char *input_data: 入力データ

  - 戻り値:

    - WEECHAT_RC_OK

    - WEECHAT_RC_ERROR

- input_callback_pointer: WeeChat が input_callback コールバックを呼び出す際にコールバックに渡すポインタ

- input_callback_data: WeeChat が input_callback コールバックを呼び出す際にコールバックに渡すポインタ; このポインタが NULL でない場合、このポインタは malloc (または類似の関数) によって割り当てられたものでなければいけません。さらに、このポインタはここで作成したバッファが閉じられた時点で自動的に開放されます

- close_callback: バッファを閉じる際に呼び出すコールバック関数、引数と戻り値:

  - const void *pointer: ポインタ

  - void *data: ポインタ

  - struct t_gui_buffer *buffer: バッファポインタ

  - 戻り値:

    - WEECHAT_RC_OK

    - WEECHAT_RC_ERROR

- close_callback_pointer: WeeChat が close_callback コールバックを呼び出す際にコールバックに渡すポインタ

- close_callback_data: WeeChat が close_callback コールバックを呼び出す際にコールバックに渡すポインタ; このポインタが NULL でない場合、このポインタは malloc (または類似の関数) によって割り当てられたものでなければいけません。さらに、このポインタはここで作成したバッファが閉じられた時点で自動的に開放されます

戻り値:

- 新しいバッファへのポインタ、エラーが起きた場合は NULL

C 言語での使用例:

    int
    my_input_cb (const void *pointer, void *data,
                 struct t_gui_buffer *buffer, const char *input_data)
    {
        weechat_printf (buffer, "Text: %s", input_data);
        return WEECHAT_RC_OK;
    }

    int
    my_close_cb (const void *pointer, void *data, struct t_gui_buffer *buffer)
    {
        weechat_printf (NULL, "Buffer _%s_ will be closed!",
                        weechat_buffer_get_string (buffer, "name"));
        return WEECHAT_RC_OK;
    }

    struct t_hashtable *properties = weechat_hashtable_new (8,
                                                            WEECHAT_HASHTABLE_STRING,
                                                            WEECHAT_HASHTABLE_STRING,
                                                            NULL,
                                                            NULL);
    /* buffer with free content */
    weechat_hashtable_set (properties, "type", "free");
    /* no logging on this buffer */
    weechat_hashtable_set (properties, "localvar_set_no_log", "1");
    /* bind key alt-c on this buffer */
    weechat_hashtable_set (properties, "key_bind_meta-c", "/my_command");

    struct t_gui_buffer *my_buffer = weechat_buffer_new_props ("my_buffer",
                                                               properties,
                                                               &my_input_cb, NULL, NULL,
                                                               &my_close_cb, NULL, NULL);

スクリプト (Python) での使用例:

    # プロトタイプ
    def buffer_new_props(name: str, properties: Dict[str, str],
                         input_callback: str, input_callback_data: str,
                         close_callback: str, close_callback_data: str) -> str: ...

    # 例
    def my_input_cb(data: str, buffer: str, input_data: str) -> int:
        weechat.prnt(buffer, "Text: %s" % input_data)
        return weechat.WEECHAT_RC_OK

    def my_close_cb(data: str, buffer: str) -> int:
        weechat.prnt("", "Buffer _%s_ will be closed!" % weechat.buffer_get_string(buffer, "name"))
        return weechat.WEECHAT_RC_OK

    properties = {
        "type": "free",                    # buffer with free content
        "localvar_set_no_log": "1",        # no logging on this buffer
        "key_bind_meta-c": "/my_command",  # bind key alt-c on this buffer
    }
    buffer = weechat.buffer_new_props("my_buffer", properties, "my_input_cb", "", "my_close_cb", "")

#### current_buffer

現在のバッファへのポインタを返す (現在のウィンドウに表示されているバッファ)。

プロトタイプ:

    struct t_gui_buffer *weechat_current_buffer ();

戻り値:

- 現在のバッファへのポインタ

C 言語での使用例:

    weechat_printf (weechat_current_buffer (), "Text on current buffer");

スクリプト (Python) での使用例:

    # プロトタイプ
    def current_buffer() -> str: ...

    # 例
    weechat.prnt(weechat.current_buffer(), "Text on current buffer")

#### buffer_search

WeeChat バージョン 1.0, 4.3.0 で更新。

Search a buffer by plugin/name, full name or unique identifier (`id`).

プロトタイプ:

    struct t_gui_buffer *weechat_buffer_search (const char *plugin,
                                                const char *name);

引数:

- plugin: name of plugin, following special values are allowed:

  - `==`: name 引数でバッファの完全な名前を使う (例: `libera.#weechat` ではなく `irc.libera.#weechat`) (WeeChat バージョン 1.0 以上で利用可)

  - `==id`: the name used is the buffer unique identifier (`id`) (WeeChat ≥ 4.3.0)

- name: バッファの名前、NULL または空文字列の場合、現在のバッファ (現在のウィンドウに表示されているバッファ) を返す; 名前が `(?i)` で始まる場合、検索は大文字小文字を区別せずに検索 (WeeChat バージョン 1.0 以上で利用可)

戻り値:

- 見つかったバッファへのポインタ、見つからない場合 NULL

C 言語での使用例:

    struct t_gui_buffer *buffer1 = weechat_buffer_search ("irc", "libera.#weechat");
    struct t_gui_buffer *buffer2 = weechat_buffer_search ("==", "irc.libera.#test");  /* WeeChat バージョン 1.0 以上で利用可 */
    struct t_gui_buffer *buffer3 = weechat_buffer_search ("==id", "1709797810942688");  /* WeeChat バージョン 4.3.0 以上で利用可 */

スクリプト (Python) での使用例:

    # プロトタイプ
    def buffer_search(plugin: str, name: str) -> str: ...

    # 例
    buffer = weechat.buffer_search("my_plugin", "my_buffer")

#### buffer_search_main

WeeChat メインバッファ (core バッファ、WeeChat を実行して最初に表示されるバッファ) を検索。

プロトタイプ:

    struct t_gui_buffer *weechat_buffer_search_main ();

戻り値:

- WeeChat メインバッファ (core バッファ) へのポインタ

C 言語での使用例:

    struct t_gui_buffer *weechat_buffer = weechat_buffer_search_main ();

スクリプト (Python) での使用例:

    # プロトタイプ
    def buffer_search_main() -> str: ...

    # 例
    buffer = weechat.buffer_search_main()

#### buffer_clear

バッファの内容を消去。

プロトタイプ:

    void weechat_buffer_clear (struct t_gui_buffer *buffer);

引数:

- buffer: バッファへのポインタ

C 言語での使用例:

    struct t_gui_buffer *my_buffer = weechat_buffer_search ("my_plugin",
                                                            "my_buffer");
    if (my_buffer)
    {
        weechat_buffer_clear (my_buffer);
    }

スクリプト (Python) での使用例:

    # プロトタイプ
    def buffer_clear(buffer: str) -> int: ...

    # 例
    buffer = weechat.buffer_search("my_plugin", "my_buffer")
    if buffer:
        weechat.buffer_clear(buffer)

#### buffer_close

バッファを閉じる。

プロトタイプ:

    void weechat_buffer_close (struct t_gui_buffer *buffer);

引数:

- buffer: バッファへのポインタ

C 言語での使用例:

    struct t_gui_buffer *my_buffer = weechat_buffer_new ("my_buffer",
                                                         &my_input_cb, NULL,
                                                         &my_close_cb, NULL);
    /* ... */
    weechat_buffer_close (my_buffer);

スクリプト (Python) での使用例:

    # プロトタイプ
    def buffer_close(buffer: str) -> int: ...

    # 例
    buffer = weechat.buffer_new("my_buffer", "my_input_cb", "", "my_close_cb", "")
    # ...
    weechat.buffer_close(buffer)

#### buffer_merge

バッファを他のバッファにマージする: 両方のバッファは同じバッファ番号を持つ独立したバッファになり、WeeChat は両方のバッファからの行を表示する (行は混合されます)。

プロトタイプ:

    void weechat_buffer_merge (struct t_gui_buffer *buffer,
                               struct t_gui_buffer *target_buffer);

引数:

- buffer: バッファへのポインタ

- target_buffer: ターゲットバッファ、マージ先のバッファ

C 言語での使用例:

    /* merge current buffer with weechat "core" buffer */
    weechat_buffer_merge (weechat_current_buffer (),
                          weechat_buffer_search_main ());

スクリプト (Python) での使用例:

    # プロトタイプ
    def buffer_merge(buffer: str, target_buffer: str) -> int: ...

    # 例
    # merge current buffer with WeeChat "core" buffer
    weechat.buffer_merge(weechat.current_buffer(), weechat.buffer_search_main())

#### buffer_unmerge

マージされたバッファからバッファのマージを解除する。

プロトタイプ:

    void weechat_buffer_unmerge (struct t_gui_buffer *buffer,
                                 int number);

引数:

- buffer: バッファへのポインタ

- number: 分離したバッファの宛先番号、1 より小さい場合、バッファは buffer の番号 + 1 になる

C 言語での使用例:

    weechat_buffer_unmerge (weechat_current_buffer (), 1);

スクリプト (Python) での使用例:

    # プロトタイプ
    def buffer_unmerge(buffer: str, number: int) -> int: ...

    # 例
    weechat.buffer_unmerge(weechat.current_buffer(), 1)

#### buffer_get_integer

バッファプロパティの整数値を返す。

プロトタイプ:

    int weechat_buffer_get_integer (struct t_gui_buffer *buffer,
                                    const char *property);

引数:

- buffer: バッファへのポインタ

- property: プロパティ名:

  - opening: 1 if buffer is opening, otherwise 0 (WeeChat ≥ 4.2.0)

  - number: バッファの番号 (1 以上)

  - layout_number: レイアウトに保存されたバッファの番号

  - layout_number_merge_order: レイアウトのマージをする際の順番

  - type: バッファタイプ (0: 書式あり、1: 自由内容)

  - notify: バッファの通知レベル

  - num_displayed: バッファを表示しているウィンドウの数

  - active: バッファがマージされて選択されている場合は 2、バッファが選択されている場合は 1、バッファがマージされ選択されていない場合は 0

  - hidden: バッファが隠されている場合は 1、そうでない場合は 0 (WeeChat バージョン 1.0 以上で利用可)

  - zoomed: バッファがマージとズームされている場合は 1、そうでない場合は 0 (WeeChat バージョン 1.0 以上で利用可)

  - print_hooks_enabled: プリントフックが有効化されている場合は 1、そうでない場合は 0

  - day_change: 日付変更メッセージを表示する場合は 1、そうでない場合は 0 (WeeChat バージョン 0.4.3 以上で利用可)

  - clear: コマンド `/buffer clear` でバッファをクリアできる場合は 1、そうでない場合は 0 (WeeChat バージョン 1.0 以上で利用可)

  - filter: バッファでフィルタが有効な場合は 1、そうでない場合は 0 (WeeChat バージョン 1.0 以上で利用可)

  - closing: 1 if buffer is closing, otherwise 0 (WeeChat ≥ 1.0)

  - lines_hidden: バッファに非表示 (フィルタされた) メッセージが 1 行以上含まれる場合は 1、すべてのメッセージが表示冴えている場合は 0

  - prefix_max_length: バッファプレフィックスの最大長

  - next_line_id: next line id in buffer (WeeChat ≥ 3.8)

  - time_for_each_line: バッファの各行に時間を表示する場合は 1 (デフォルト)、そうでない場合は 0

  - nicklist: ニックネームリストが有効化されている場合は 1、そうでない場合は 0

  - nicklist_case_sensitive: ニックネームの大文字小文字を区別する場合は 1、そうでない場合は 0

  - nicklist_max_length: ニックネームの最大長

  - nicklist_display_groups: グループを表示する場合 1、そうでない場合は 0

  - nicklist_count: ニックネームリストに含まれるニックネームとグループの数

  - nicklist_visible_count: number of nicks/groups displayed

  - nicklist_groups_count: ニックネームリストに含まれるグループの数

  - nicklist_groups_visible_count: number of groups displayed

  - nicklist_nicks_count: ニックネームリストに含まれるニックネームの数

  - nicklist_nicks_visible_count: number of nicks displayed

  - input: 入力可能な場合は 1、そうでない場合は 0

  - input_get_any_user_data: 1 if any user data, including commands, are sent to input callback, otherwise 0

  - input_get_unknown_commands: 未定義のコマンドを入力コールバックに送信する場合は 1、そうでない場合は 0

  - input_get_empty: 入力コールバックに何も送信されなかった場合は 1、そうでない場合は 0

  - input_multiline: 1 if multiple lines are sent as one message to input callback, otherwise 0

  - input_size: 入力サイズ (バイト単位)

  - input_length: 入力長 (文字数)

  - input_pos: バッファ入力におけるカーソル位置

  - input_1st_display: バッファ入力における 1 文字目

  - num_history: コマンド履歴の数

  - text_search: テキスト検索タイプ:

    - 0: 現在検索していない

    - 1: search in buffer lines

    - 2: search in commands history

  - text_search_direction: direction for search:

    - 0: backward search (direction: oldest messages/commands)

    - 1: forward search (direction: newest messages/commands)

  - text_search_exact: テキスト検索で大文字小文字を区別する場合は 1

  - text_search_regex: 1 if searching with a regular expression

  - text_search_where:

    - 0: 現在検索していない

    - 1: search in message

    - 2: search in prefix

    - 3: search in prefix and message

  - text_search_history:

    - 0: 現在検索していない

    - 1: search in buffer local history

    - 2: search in global history

  - text_search_found: テキストが見つかった場合は 1、そうでない場合は 0

戻り値:

- プロパティの整数値

C 言語での使用例:

    weechat_printf (NULL, "my buffer number is: %d",
                    weechat_buffer_get_integer (my_buffer, "number"));

スクリプト (Python) での使用例:

    # プロトタイプ
    def buffer_get_integer(buffer: str, property: str) -> int: ...

    # 例
    weechat.prnt("", "my buffer number is: %d" % weechat.buffer_get_integer(my_buffer, "number"))

#### buffer_get_string

バッファプロパティの文字列値を返す。

プロトタイプ:

    const char *weechat_buffer_get_string (struct t_gui_buffer *buffer,
                                           const char *property);

引数:

- buffer: バッファへのポインタ

- property: プロパティ名:

  - id: unique identifier (WeeChat ≥ 4.3.0)

  - plugin: バッファを作成したプラグインの名前 ("core" は WeeChat メインバッファ)

  - name: バッファの名前

  - full_name: バッファの完全な名前 ("plugin.name") (WeeChat バージョン 0.3.7 以上で利用可)

  - old_full_name: old full name of buffer ("plugin.name"), set before the buffer is renamed (WeeChat ≥ 2.8)

  - short_name: バッファの短縮名 (注意: 表示目的以外に使用するのは禁止、ユーザは書き換えることが可能、バッファを検索する際にこれを使ってはいけない、name、full_name、またはローカル変数 channel を使うこと)

  - type: type of buffer: "formatted" or "free" (WeeChat ≥ 4.2.0)

  - title: バッファのタイトル

  - modes: modes (WeeChat ≥ 4.3.0)

  - nicklist_last_id_assigned: last unique identifier used in this buffer for a group or nick (WeeChat ≥ 4.3.0)

  - input_prompt: input prompt (WeeChat ≥ 4.3.0)

  - input: 入力テキスト

  - text_search_input: テキスト検索前に保存した入力テキスト

  - highlight_words: ハイライトする単語のリスト

  - highlight_disable_regex: POSIX extended regular expression for disabling highlight

  - highlight_regex: ハイライト用の POSIX 拡張正規表現

  - highlight_tags_restrict: これらのタグを付けられたメッセージだけにハイライトを制限する

  - highlight_tags: これらのタグを付けられたメッセージを強制的にハイライトする

  - hotlist_max_level_nicks: 一部のニックネームに対するホットリストレベルの最大値

  - localvar_xxx: ローカル変数 "xxx" の値 ("xxx" は読み出す変数の名前)

戻り値:

- プロパティの文字列値

C 言語での使用例:

    weechat_printf (NULL, "name / short name of buffer are: %s / %s",
                    weechat_buffer_get_string (my_buffer, "name"),
                    weechat_buffer_get_string (my_buffer, "short_name"));

スクリプト (Python) での使用例:

    # プロトタイプ
    def buffer_get_string(buffer: str, property: str) -> str: ...

    # 例
    weechat.prnt("", "name / short name of buffer are: %s / %s"
        % (weechat.buffer_get_string(my_buffer, "name"),
        weechat.buffer_get_string(my_buffer, "short_name")))

#### buffer_get_pointer

バッファプロパティのポインタ値を返す。

プロトタイプ:

    void *weechat_buffer_pointer (struct t_gui_buffer *buffer,
                                  const char *property);

引数:

- buffer: バッファへのポインタ

- property: プロパティ名:

  - plugin: このバッファを作ったプラグインへのポインタ (WeeChat メインバッファの場合は NULL)

  - text_search_regex_compiled: compiled regular expression

  - text_search_ptr_history: history found

  - highlight_disable_regex_compiled: コンパイル済みの正規表現 highlight_disable_regex

  - highlight_regex_compiled: コンパイル済みの正規表現 highlight_regex

戻り値:

- プロパティのポインタ値

C 言語での使用例:

    weechat_printf (NULL, "plugin pointer of my buffer: %p",
                    weechat_buffer_get_pointer (my_buffer, "plugin"));

スクリプト (Python) での使用例:

    # プロトタイプ
    def buffer_get_pointer(buffer: str, property: str) -> str: ...

    # 例
    weechat.prnt("", "plugin pointer of my buffer: %s" % weechat.buffer_get_pointer(my_buffer, "plugin"))

#### buffer_set

バッファプロパティに文字列値を設定。

プロトタイプ:

    void weechat_buffer_set (struct t_gui_buffer *buffer, const char *property,
                             const char *value);

引数:

- buffer: バッファへのポインタ

- property: プロパティ名 (以下の表を参照)

- value: プロパティの新しい値

プロパティ:

名前 | Min WeeChat | 値 | 説明
--- | --- | --- | ---
hotlist |  | "+", "-", WEECHAT_HOTLIST_LOW, WEECHAT_HOTLIST_MESSAGE, WEECHAT_HOTLIST_PRIVATE, WEECHAT_HOTLIST_HIGHLIGHT, "-1" | "+": ホットリストを有効化 (グローバル設定、バッファへのポインタは使われない) "-": ホットリストを無効化 (グローバル設定、バッファへのポインタは使われない) 優先度: この優先度でホットリストにバッファを追加 (conditions defined in option weechat.look.hotlist_add_conditions are NOT checked) "-1": ホットリストからバッファを削除 (WeeChat バージョン 1.0 以上で利用可)
hotlist_conditions | 4.5.0 | WEECHAT_HOTLIST_LOW, WEECHAT_HOTLIST_MESSAGE, WEECHAT_HOTLIST_PRIVATE, WEECHAT_HOTLIST_HIGHLIGHT | priority: add buffer to hotlist with this priority (conditions defined in option weechat.look.hotlist_add_conditions are checked).
completion_freeze |  | "0" または "1" | "0": 補完を止める (デフォルト) (グローバル設定、バッファへのポインタは使われない) "1": コマンドラインが更新された際に補完を継続する (グローバル設定、バッファへのポインタは使われない)
unread |  | empty string, "0", "+N", "-N" or "N" (N is integer) | empty string: set unread marker after last line of buffer "0": remove unread marker from buffer "N": move the unread marker N lines from the end towards the first line of buffer "-N": move the unread marker N lines towards the first line of buffer "+N": move the unread marker N lines towards the last line of buffer.
display |  | "1" または "auto" | "1": 指定したバッファを現在のウィンドウに表示 "auto": 指定したバッファを現在のウィンドウに表示、読了マーカーをリセットしない
hidden | 1.0 | "0" または "1" | "0": バッファを隠すことを止める "1": バッファを隠す
number |  | 番号 | 指定したバッファをこの番号に移動
name |  | 任意の文字列 | 指定したバッファの新しい名前を設定
short_name |  | 任意の文字列 | 指定したバッファの新しい短縮名を設定
type |  | "formatted" または "free" | バッファのタイプを設定: "formatted" (チャットメッセージ用)、または "free" (自由内容用); 値が "free" の場合、clear プロパティは強制的に "0" に設定されます (WeeChat バージョン 1.0 以上で利用可)
notify |  | "0", "1", "2", "3" | バッファの通知レベルを設定: "0" = ホットリストに追加しない、"1" = ハイライトされた場合のみ追加、"2" = ハイライトされた場合とメッセージを受信した場合に追加、"3" = 任意のメッセージを受信した場合に追加
print_hooks_enabled |  | "0" or "1" | プリントフックを無効化する場合は "0"、有効化する場合は "1" (新規バッファに対するデフォルト)
day_change | 0.4.3 | "0" または "1" | 日付変更メッセージを隠す場合は "0"、表示する場合は "1" (新規バッファに対するデフォルト)
clear | 1.0 | "0" または "1" | ユーザからのコマンド `/buffer clear` でバッファのクリアを禁止する場合は "0"、バッファのクリアを許可する場合は "1" (新規バッファに対するデフォルト) (注意: この値が "0" に設定されていたとしても、関数 buffer_clear を使えばバッファをクリアすることが可能です)
filter | 1.0 | "0" または "1" | "0": バッファでフィルタを無効化 "1": バッファでフィルタを有効化
title |  | 任意の文字列 | 指定したバッファの新しいタイトルを設定
modes | 4.3.0 | any string | Set new modes for buffer.
time_for_each_line |  | "0" または "1" | バッファのすべての行に時間を表示しない場合は "0"、表示する場合は "1" (新規バッファに対するデフォルト)
nicklist |  | "0" または "1" | バッファのニックネームリストを表示しない場合は "0"、表示する場合は "1"
nicklist_case_sensitive |  | "0" または "1" | ニックネームリストで大文字小文字を区別しない場合は "0"、区別する場合は "1"
nicklist_display_groups |  | "0" または "1" | ニックネームリストグループを隠す場合は "0"、表示する場合は "1"
highlight_words |  | "-" または単語のコンマ区切りリスト | 任意のハイライトを無効化する場合は特殊値 "-"、または指定したバッファ内でハイライトする単語のコンマ区切りリスト、例: "abc,def,ghi"
highlight_words_add |  | 単語のコンマ区切りリスト | 指定したバッファ内でハイライトする単語のコンマ区切りリスト、これらの単語を指定したバッファ内でハイライトする単語に追加します
highlight_words_del |  | 単語のコンマ区切りリスト | 指定したバッファ内でハイライトする単語から削除する単語のコンマ区切りリスト
highlight_disable_regex |  | any string | POSIX extended regular expression for disabling highlight.
highlight_regex |  | 任意の文字列 | ハイライトする POSIX 拡張正規表現
highlight_tags_restrict |  | タグのコンマ区切りリスト | 指定したバッファ内でこれらのタグをつけられたメッセージだけを対象にハイライトする (区切り文字 "+" で論理 "and" を表現することにより複数のタグを組み合わせて使うことができます、例: "nick_toto+irc_action")
highlight_tags |  | タグのコンマ区切りリスト | 指定したバッファ内でこれらのタグをつけられたメッセージを強制的にハイライトする (区切り文字 "+" で論理 "and" を表現することにより複数のタグを組み合わせて使うことができます、例: "nick_toto+irc_action")
hotlist_max_level_nicks |  | "nick:level" のコンマ区切りリスト | 指定したバッファに対するホットリストの最大レベルを付けたニックネームのコンマ区切りリスト (レベル: -1: ホットリストに追加しない、0: 低い、1: メッセージ、2: プライベート、3: ハイライト)、例: "joe:2,mike:-1,robert:-1" (joe さんのメッセージはハイライトされない、mike さんと robert さんはホットリストを変更しない)
hotlist_max_level_nicks_add |  | "nick:level" のコンマ区切りリスト | ホットリストの最大レベルを付けたニックネームのコンマ区切りリスト、これらのニックネームを指定したバッファ内のニックネームに追加します
hotlist_max_level_nicks_del |  | ニックネームのコンマ区切りリスト | ホットリストの最大レベルから削除するニックネームのコンマ区切りリスト
key_bind_xxx |  | 任意の文字列 | 指定したバッファに対して新しいキー xxx を割り当てる、値はキーを押して実行するコマンド
key_unbind_xxx |  | - | 指定したバッファに対してキー xxx の割り当てを解除する
input_prompt | 4.3.0 | any string | Set new value for input prompt.
input |  | 任意の文字列 | バッファ入力に新しい値を設定
input_pos |  | 位置 | バッファ入力のカーソル位置を設定
input_get_any_user_data | 4.3.0 | "0" or "1" | "0" to get only user messages (default behavior), "1" to get everything, including commands.
input_get_unknown_commands |  | "0" または "1" | 指定したバッファに対する未定義のコマンドを無効にする場合は "0" (デフォルト)、未定義のコマンドを受け入れる場合は "1"、例えばユーザが "/unknowncmd" を入力した場合、バッファはこれを受け入れる (未定義のコマンドに対するエラーを出さない)
input_get_empty |  | "0" または "1" | バッファに対する空入力を受け取らない場合は "0" (デフォルト)、空入力を受け取る場合は "1"
input_multiline |  | "0" または "1" | "0" to send each line separately to this buffer (default behavior), "1" to send multiple lines as a single message.
localvar_set_xxx |  | 任意の文字列 | ローカル変数 xxx の新しい値を設定 (存在しない変数の場合は変数を作成する)
localvar_del_xxx |  | - | ローカル変数 xxx を削除

C 言語での使用例:

    /* disable hotlist (for all buffers) */
    weechat_buffer_set (NULL, "hotlist", "-");

    /* enable again hotlist */
    weechat_buffer_set (NULL, "hotlist", "+");

    /* change buffer name */
    weechat_buffer_set (my_buffer, "name", "my_new_name");

    /* add new local variable "toto" with value "abc" */
    weechat_buffer_set (my_buffer, "localvar_set_toto", "abc");

    /* remove local variable "toto" */
    weechat_buffer_set (my_buffer, "localvar_del_toto", "");

スクリプト (Python) での使用例:

    # プロトタイプ
    def buffer_set(buffer: str, property: str, value: str) -> int: ...

    # 例

    # disable hotlist (for all buffers)
    weechat.buffer_set("", "hotlist", "-")

    # enable again hotlist
    weechat.buffer_set("", "hotlist", "+")

    # change buffer name
    weechat.buffer_set(my_buffer, "name", "my_new_name")

    # add new local variable "toto" with value "abc"
    weechat.buffer_set(my_buffer, "localvar_set_toto", "abc")

    # remove local variable "toto"
    weechat.buffer_set(my_buffer, "localvar_del_toto", "")

#### buffer_set_pointer

バッファプロパティのポインタ値を設定。

プロトタイプ:

    void weechat_buffer_set_pointer (struct t_gui_buffer *buffer, const char *property,
                                     void *pointer);

引数:

- buffer: バッファへのポインタ

- property: プロパティ名:

  - close_callback: バッファを閉じる際に呼び出すコールバック関数を設定

  - close_callback_data: バッファを閉じる際に呼び出すコールバック関数に渡すデータを設定

  - input_callback: 入力テキストをバッファに挿入する際に呼び出すコールバック関数を設定

  - input_callback_data: 入力テキストをバッファに挿入する際に呼び出すコールバック関数に渡すデータを設定

  - nickcmp_callback: ニックネーム比較コールバック関数を設定 (ニックネームリストからニックネームを検索する際にこのコールバックを使用) (WeeChat バージョン 0.3.9 以上で利用可)

  - nickcmp_callback_data: ニックネーム比較コールバック関数に渡すデータを設定 (WeeChat バージョン 0.3.9 以上で利用可)

- pointer: プロパティの新しいポインタ値

コールバックのプロトタイプ:

    int close_callback (const void *pointer, void *data,
                        struct t_gui_buffer *buffer);

    int input_callback (const void *pointer, void *data,
                        struct t_gui_buffer *buffer, const char *input_data);

    int nickcmp_callback (const void *pointer, void *data,
                          struct t_gui_buffer *buffer,
                          const char *nick1, const char *nick2);

C 言語での使用例:

    int
    my_close_cb (const void *pointer, void *data, struct t_gui_buffer *buffer)
    {
        /* ... */
        return WEECHAT_RC_OK;
    }

    weechat_buffer_set_pointer (my_buffer, "close_callback", &my_close_cb);

注記 | スクリプト API ではこの関数を利用できません。

#### buffer_string_replace_local_var

文字列に含まれるバッファローカル変数をその値で展開する。

プロトタイプ:

    char *weechat_buffer_string_replace_local_var (struct t_gui_buffer *buffer,
                                                   const char *string);

引数:

- buffer: バッファへのポインタ

- string: テキストおよび書式 "$var" のローカル変数を含む文字列

戻り値:

- ローカル変数を展開した文字列

C 言語での使用例:

    weechat_buffer_set (my_buffer, "localvar_set_toto", "abc");

    char *str = weechat_buffer_string_replace_local_var (my_buffer,
                                                         "test with $toto");
    /* str contains "test with abc" */

スクリプト (Python) での使用例:

    # プロトタイプ
    def buffer_string_replace_local_var(buffer: str, string: str) -> str: ...

    # 例
    weechat.buffer_set(my_buffer, "localvar_set_toto", "abc")
    str = weechat.buffer_string_replace_local_var(my_buffer, "test with $toto")
    # str contains "test with abc"

#### buffer_match_list

WeeChat ≥ 0.3.5, updated in 4.0.0.

バッファがバッファのリストにマッチすることを確認。

プロトタイプ:

    int weechat_buffer_match_list (struct t_gui_buffer *buffer, const char *string);

引数:

- buffer: バッファへのポインタ

- string: バッファのコンマ区切りリスト:

  - `*` 任意のバッファにマッチ

  - 名前の最初に `!` がある場合はその名前を含まない場合にマッチ

  - 名前にワイルドカード `*` を使うことができます

注記 | Since version 4.0.0, comparison of buffer names is case-sensitive.

戻り値:

- バッファがバッファリストにマッチする場合は 1、そうでない場合は 0

C 言語での使用例:

    struct t_gui_buffer *buffer = weechat_buffer_search ("irc", "libera.#weechat");
    if (buffer)
    {
        weechat_printf (NULL, "%d", weechat_buffer_match_list (buffer, "*"));                    /* 1 */
        weechat_printf (NULL, "%d", weechat_buffer_match_list (buffer, "*,!*#weechat*"));        /* 0 */
        weechat_printf (NULL, "%d", weechat_buffer_match_list (buffer, "irc.libera.*"));         /* 1 */
        weechat_printf (NULL, "%d", weechat_buffer_match_list (buffer, "irc.oftc.*,python.*"));  /* 0 */
    }

スクリプト (Python) での使用例:

    # プロトタイプ
    def buffer_match_list(buffer: str, string: str) -> int: ...

    # 例
    buffer = weechat.buffer_search("irc", "libera.#weechat")
    if buffer:
        weechat.prnt("", "%d" % weechat.buffer_match_list(buffer, "*"))                    # 1
        weechat.prnt("", "%d" % weechat.buffer_match_list(buffer, "*,!*#weechat*"))        # 0
        weechat.prnt("", "%d" % weechat.buffer_match_list(buffer, "irc.libera.*"))         # 1
        weechat.prnt("", "%d" % weechat.buffer_match_list(buffer, "irc.oftc.*,python.*"))  # 0

### 3.16. Buffer lines

Functions for buffer lines.

#### line_search_by_id

WeeChat ≥ 4.4.0.

Search line in buffer by identifier.

プロトタイプ:

    struct t_gui_line *weechat_line_search_by_id (struct t_gui_buffer *buffer, int id);

戻り値:

- pointer to line found, NULL if not found

C 言語での使用例:

    struct t_gui_line *line = weechat_line_search_by_id (buffer, 123);

スクリプト (Python) での使用例:

    # プロトタイプ
    def line_search_by_id(buffer: str, line_id: int) -> str: ...

    # 例
    line = weechat.line_search_by_id(buffer, 123)

### 3.17. ウィンドウ

ウィンドウを操作する関数。

#### current_window

現在のウィンドウへのポインタを返す。

プロトタイプ:

    struct t_gui_window *weechat_current_window ();

戻り値:

- 現在のウィンドウへのポインタ

C 言語での使用例:

    struct t_gui_window *current_window = weechat_current_window ();

スクリプト (Python) での使用例:

    # プロトタイプ
    def current_window() -> str: ...

    # 例
    current_window = weechat.current_window()

#### window_search_with_buffer

WeeChat バージョン 0.3.5 以上で利用可。

バッファを表示しているウィンドウへのポインタを返す。

プロトタイプ:

    struct t_gui_window *weechat_window_search_with_buffer (struct t_gui_buffer *buffer);

引数:

- buffer: バッファへのポインタ

戻り値:

- バッファを表示しているウィンドウへのポインタ (バッファを表示しているウィンドウが無い場合は NULL)

C 言語での使用例:

    weechat_printf (NULL,
                    "window displaying core buffer: %p",
                    weechat_window_search_with_buffer (weechat_buffer_search_main ()));

スクリプト (Python) での使用例:

    # プロトタイプ
    def window_search_with_buffer(buffer: str) -> str: ...

    # 例
    weechat.prnt("", "window displaying core buffer: %s"
        % weechat.window_search_with_buffer(weechat.buffer_search_main()))

#### window_get_integer

ウィンドウプロパティの整数値を返す。

プロトタイプ:

    int weechat_window_get_integer (struct t_gui_window *window,
                                    const char *property);

引数:

- window: ウィンドウへのポインタ

- property: プロパティ名:

  - number: ウィンドウ番号 (1 以上)

  - win_x: 端末内でのウィンドウの X 座標 (1 列目は 0)

  - win_y: 端末内でのウィンドウの Y 座標 (1 行目は 0)

  - win_width: ウィンドウの横幅、文字単位

  - win_height: ウィンドウの縦幅、文字単位

  - win_width_pct: ウィンドウ横幅の百分率、親ウィンドウに対する割合 (例えば 50 は半分を意味する)

  - win_height_pct: ウィンドウ縦幅の百分率、親ウィンドウに対する割合 (例えば 50 は半分を意味する)

  - win_chat_x: チャットウィンドウの X 座標 (1 列目は 0)

  - win_chat_y: チャットウィンドウの Y 座標 (1 行目は 0)

  - win_chat_width: チャットウィンドウの横幅、文字単位

  - win_chat_height: チャットウィンドウの縦幅、文字単位

  - first_line_displayed: バッファの 1 行目が画面に表示されている場合は 1、そうでなければ 0

  - scrolling: ウィンドウでスクロールが有効化されている場合 (最後の行が表示されていない場合) は 1

  - lines_after: バッファの最終行を表示した後にバッファに追加された行の数 (スクロール中)

戻り値:

- プロパティの整数値

C 言語での使用例:

    weechat_printf (NULL, "current window is at position (x,y): (%d,%d)",
                    weechat_window_get_integer (weechat_current_window (), "win_x"),
                    weechat_window_get_integer (weechat_current_window (), "win_y"));

スクリプト (Python) での使用例:

    # プロトタイプ
    def window_get_integer(window: str, property: str) -> int: ...

    # 例
    weechat.prnt("", "current window is at position (x,y): (%d,%d)"
        % (weechat.window_get_integer(weechat.current_window(), "win_x"),
        weechat.window_get_integer(weechat.current_window(), "win_y")))

#### window_get_string

ウィンドウプロパティの文字列値を返す。

注記 | 現在この関数を使うことはできません、将来のバージョン用に予約されています。

プロトタイプ:

    const char *weechat_window_get_string (struct t_gui_window *window,
                                           const char *property);

引数:

- window: ウィンドウへのポインタ

- property: プロパティ名

戻り値:

- プロパティの文字列値

スクリプト (Python) での使用例:

    # プロトタイプ
    def window_get_string(window: str, property: str) -> str: ...

#### window_get_pointer

ウィンドウプロパティのポインタ値を返す。

プロトタイプ:

    void *weechat_window_get_pointer (struct t_gui_window *window,
                                      const char *property);

引数:

- window: ウィンドウへのポインタ

- property: プロパティ名:

  - current: 現在のウィンドウへのポインタ

  - buffer: 指定したウィンドウが表示しているバッファへのポインタ

戻り値:

- プロパティのポインタ値

C 言語での使用例:

    weechat_printf (NULL,
                    "buffer displayed in current window: %p",
                    weechat_window_get_pointer (weechat_current_window (), "buffer"));

スクリプト (Python) での使用例:

    # プロトタイプ
    def window_get_pointer(window: str, property: str) -> str: ...

    # 例
    weechat.prnt("", "buffer displayed in current window: %s"
        % weechat.window_get_pointer(weechat.current_window(), "buffer"))

#### window_set_title

端末のタイトルを設定。

プロトタイプ:

    void weechat_window_set_title (const char *title);

引数:

- title: 端末の新しいタイトル; この文字列は評価されるため、文字列内に `${info:version}` などの変数を含めることが可能です (string_eval_expression を参照)

C 言語での使用例:

    weechat_window_set_title ("new title here");

スクリプト (Python) での使用例:

    # プロトタイプ
    def window_set_title(title: str) -> int: ...

    # 例
    weechat.window_set_title("new title here")

### 3.18. ニックネームリスト

バッファのニックネームリストを操作する関数。

#### nicklist_add_group

ニックネームリストにグループを追加。

プロトタイプ:

    struct t_gui_nick_group *weechat_nicklist_add_group (struct t_gui_buffer *buffer,
                                                         struct t_gui_nick_group *parent_group,
                                                         const char *name,
                                                         const char *color,
                                                         int visible);

引数:

- buffer: バッファへのポインタ

- parent_group: グループの親へのポインタ、グループに親がない場合 NULL (ニックネームリスト)

- name: グループ名

- color: 色オプション名:

  - WeeChat オプション名、例えば weechat.color.nicklist_group

  - 任意で背景色をつけた色、例えば yellow や yellow,red

  - バーの色名:

    - bar_fg: バーの前景色

    - bar_delim: バーの区切り文字

    - bar_bg: バーの背景色

- visible:

  - 1: グループとサブグループおよびニックネームを表示

  - 0: グループとサブグループおよびニックネームを非表示

注記 | グループ名の前に、1 桁以上の数字とパイプ文字を付けると、この数字を使ってニックネームリスト内のグループをソートします。例えば、グループ "1|test" と "2|abc" はこの順番で表示されます: 最初に "test" その後に "abc"。

戻り値:

- 新しいグループへのポインタ、エラーが起きた場合は NULL

C 言語での使用例:

    struct t_gui_nick_group *my_group =
        weechat_nicklist_add_group (my_buffer,
                                    my_parent_group,
                                    "test_group",
                                    "weechat.color.nicklist_group",
                                    1);

スクリプト (Python) での使用例:

    # プロトタイプ
    def nicklist_add_group(buffer: str, parent_group: str, name: str, color: str, visible: int) -> str: ...

    # 例
    group = weechat.nicklist_add_group(my_buffer, my_parent_group, "test_group",
        "weechat.color.nicklist_group", 1)

#### nicklist_search_group

WeeChat バージョン 4.3.0 で更新。

Search a group in a nicklist by name or unique identifier (`id`).

プロトタイプ:

    struct t_gui_nick_group *weechat_nicklist_search_group (struct t_gui_buffer *buffer,
                                                            struct t_gui_nick_group *from_group,
                                                            const char *name);

引数:

- buffer: バッファへのポインタ

- from_group: このグループのみを検索、全てのニックネームリストから検索する場合は NULL

- name: group name to search; with WeeChat ≥ 4.3.0, a unique identifier can be given with the format: `==id:xxx` (where `xxx` is the identifier)

戻り値:

- 見つかったグループへのポインタ、見つからなかった場合は NULL

C 言語での使用例:

    struct t_gui_nick_group *ptr_group1 = weechat_nicklist_search_group (my_buffer,
                                                                         NULL, "test_group");
    struct t_gui_nick_group *ptr_group2 = weechat_nicklist_search_group (my_buffer,
                                                                         NULL, "==id:1714382231198764");

スクリプト (Python) での使用例:

    # プロトタイプ
    def nicklist_search_group(buffer: str, from_group: str, name: str) -> str: ...

    # 例
    group1 = weechat.nicklist_search_group(my_buffer, "", "test_group")
    group2 = weechat.nicklist_search_group(my_buffer, "", "==id:1714382231198764")

#### nicklist_add_nick

ニックネームをグループに追加。

プロトタイプ:

    struct t_gui_nick *weechat_nicklist_add_nick (struct t_gui_buffer *buffer,
                                                  struct t_gui_nick_group *group,
                                                  const char *name,
                                                  const char *color,
                                                  const char *prefix,
                                                  const char *prefix_color,
                                                  int visible);

引数:

- buffer: バッファへのポインタ

- group: グループへのポインタ

- name: ニックネーム

- color: 色オプション名:

  - WeeChat オプション名 (weechat.color.xxx のオプション部分)、例えば chat_delimiters

  - 任意で背景色をつけた色、例えば yellow や yellow,red

  - バーの色名:

    - bar_fg: バーの前景色

    - bar_delim: バーの区切り文字

    - bar_bg: バーの背景色

- prefix: ニックネームの前に表示するプレフィックス

- prefix_color: 色オプション名:

  - WeeChat オプション名 (weechat.color.xxx のオプション部分)、例えば chat_delimiters

  - 任意で背景色をつけた色、例えば yellow や yellow,red

  - バーの色名:

    - bar_fg: バーの前景色

    - bar_delim: バーの区切り文字

    - bar_bg: バーの背景色

- visible:

  - 1: ニックネームを表示

  - 0: ニックネームを非表示

戻り値:

- 新しいニックネームへのポインタ、エラーが起きた場合は NULL

C 言語での使用例:

    struct t_gui_nick *my_nick =
        weechat_nicklist_add_nick (my_buffer, my_group,
                                   "test_nick",
                                   (nick_away) ? "weechat.color.nicklist_away" : "bar_fg",
                                   "@", "lightgreen",
                                   1);

スクリプト (Python) での使用例:

    # プロトタイプ
    def nicklist_add_nick(buffer: str, group: str, name: str, color: str, prefix: str, prefix_color: str, visible: int) -> str: ...

    # 例
    if nick_away:
        color = "weechat.color.nicklist_away"
    else:
        color = "bar_fg"
    nick = weechat.nicklist_add_nick(my_buffer, my_group, "test_nick", color, "@", "lightgreen", 1)

#### nicklist_search_nick

WeeChat バージョン 4.3.0 で更新。

Search a nick in a nicklist by name or unique identifier (`id`).

プロトタイプ:

    struct t_gui_nick *weechat_nicklist_search_nick (struct t_gui_buffer *buffer,
                                                     struct t_gui_nick_group *from_group,
                                                     const char *name);

引数:

- buffer: バッファへのポインタ

- from_group: このグループのみを検索、全てのニックネームリストから検索する場合は NULL

- name: nick name to search; with WeeChat ≥ 4.3.0, a unique identifier can be given with the format: `==id:xxx` (where `xxx` is the identifier)

戻り値:

- 見つかったニックネームへのポインタ、見つからなかった場合は NULL

C 言語での使用例:

    struct t_gui_nick *ptr_nick1 = weechat_nicklist_search_nick (my_buffer,
                                                                 NULL, "test_nick");
    struct t_gui_nick *ptr_nick2 = weechat_nicklist_search_nick (my_buffer,
                                                                 NULL, "==id:1714382252187496");

スクリプト (Python) での使用例:

    # プロトタイプ
    def nicklist_search_nick(buffer: str, from_group: str, name: str) -> str: ...

    # 例
    nick1 = weechat.nicklist_search_nick(my_buffer, "", "test_nick")
    nick2 = weechat.nicklist_search_nick(my_buffer, "", "==id:1714382252187496")

#### nicklist_remove_group

ニックネームリストからグループを削除。

プロトタイプ:

    void weechat_nicklist_remove_group (struct t_gui_buffer *buffer,
                                        struct t_gui_nick_group *group);

引数:

- buffer: バッファへのポインタ

- group: 削除するグループへのポインタ (同時に全てのサブグループおよびニックネームを削除)

C 言語での使用例:

    weechat_nicklist_remove_group (my_buffer, my_group);

スクリプト (Python) での使用例:

    # プロトタイプ
    def nicklist_remove_group(buffer: str, group: str) -> int: ...

    # 例
    weechat.nicklist_remove_group(my_buffer, my_group)

#### nicklist_remove_nick

ニックネームリストからニックネームを削除。

プロトタイプ:

    void weechat_nicklist_remove_nick (struct t_gui_buffer *buffer,
                                       struct t_gui_nick *nick);

引数:

- buffer: バッファへのポインタ

- nick: 削除するニックネームへのポインタ

C 言語での使用例:

    weechat_nicklist_remove_nick (my_buffer, my_nick);

スクリプト (Python) での使用例:

    # プロトタイプ
    def nicklist_remove_nick(buffer: str, nick: str) -> int: ...

    # 例
    weechat.nicklist_remove_nick(my_buffer, my_nick)

#### nicklist_remove_all

ニックネームリストから全てのグループおよびニックネームを削除。

プロトタイプ:

    void weechat_nicklist_remove_all (struct t_gui_buffer *buffer);

引数:

- buffer: バッファへのポインタ

C 言語での使用例:

    weechat_nicklist_remove_all (my_buffer);

スクリプト (Python) での使用例:

    # プロトタイプ
    def nicklist_remove_all(buffer: str) -> int: ...

    # 例
    weechat.nicklist_remove_all(my_buffer)

#### nicklist_get_next_item

WeeChat バージョン 0.3.7 以上で利用可。

ニックネームリストから次のグループまたはニックネームを取得 (主にニックネームリストを表示する際に利用)。

プロトタイプ:

    void weechat_nicklist_get_next_item (struct t_gui_buffer *buffer,
                                         struct t_gui_nick_group **group,
                                         struct t_gui_nick **nick);

引数:

- buffer: バッファへのポインタ

- group: グループへのポインタへのポインタ

- nick: ニックネームへのポインタへのポインタ

C 言語での使用例:

    struct t_gui_nick_group *ptr_group;
    struct t_gui_nick *ptr_nick;

    ptr_group = NULL;
    ptr_nick = NULL;
    weechat_nicklist_get_next_item (buffer, &ptr_group, &ptr_nick);
    while (ptr_group || ptr_nick)
    {
        if (ptr_nick)
        {
            /* nick */
            /* ... */
        }
        else
        {
            /* group */
            /* ... */
        }
        weechat_nicklist_get_next_item (buffer, &ptr_group, &ptr_nick);
    }

注記 | スクリプト API ではこの関数を利用できません。

#### nicklist_group_get_integer

WeeChat バージョン 0.3.4 以上で利用可。

グループプロパティの整数値を返す。

プロトタイプ:

    int weechat_nicklist_group_get_integer (struct t_gui_buffer *buffer,
                                            struct t_gui_nick_group *group,
                                            const char *property);

引数:

- buffer: バッファへのポインタ

- group: グループへのポインタ

- property: プロパティ名:

  - visible: グループが表示されている場合は 1、そうでない場合は 0

  - level: グループレベル (ルートは 0)

戻り値:

- プロパティの整数値

C 言語での使用例:

    int visible = weechat_nicklist_group_get_integer (buffer, group, "visible");

スクリプト (Python) での使用例:

    # プロトタイプ
    def nicklist_group_get_integer(buffer: str, group: str, property: str) -> int: ...

    # 例
    visible = weechat.nicklist_group_get_integer(buffer, group, "visible")

#### nicklist_group_get_string

WeeChat バージョン 0.3.4 以上で利用可。

グループプロパティの文字列値を返す。

プロトタイプ:

    const char *weechat_nicklist_group_get_string (struct t_gui_buffer *buffer,
                                                   struct t_gui_nick_group *group,
                                                   const char *property);

引数:

- buffer: バッファへのポインタ

- group: グループへのポインタ

- property: プロパティ名:

  - id: unique identifier (WeeChat ≥ 4.3.0)

  - name: グループの名前

  - color: ニックネームリストのグループ色

戻り値:

- プロパティの文字列値

C 言語での使用例:

    const char *color = weechat_nicklist_group_get_string (buffer, group, "color");

スクリプト (Python) での使用例:

    # プロトタイプ
    def nicklist_group_get_string(buffer: str, group: str, property: str) -> str: ...

    # 例
    color = weechat.nicklist_group_get_string(buffer, group, "color")

#### nicklist_group_get_pointer

WeeChat バージョン 0.3.4 以上で利用可。

グループプロパティのポインタ値を返す。

プロトタイプ:

    void *weechat_nicklist_group_get_pointer (struct t_gui_buffer *buffer,
                                              struct t_gui_nick_group *group,
                                              const char *property);

引数:

- buffer: バッファへのポインタ

- group: グループへのポインタ

- property: プロパティ名:

  - parent: 親グループへのポインタ

戻り値:

- プロパティのポインタ値

C 言語での使用例:

    struct t_gui_nick_group *parent = weechat_nicklist_group_get_pointer (buffer, group, "parent");

スクリプト (Python) での使用例:

    # プロトタイプ
    def nicklist_group_get_pointer(buffer: str, group: str, property: str) -> str: ...

    # 例
    parent = weechat.nicklist_group_get_pointer(buffer, group, "parent")

#### nicklist_group_set

WeeChat ≥ 0.3.4, updated in 4.3.0.

グループプロパティの文字列値。

プロトタイプ:

    void weechat_nicklist_group_set (struct t_gui_buffer *buffer,
                                     struct t_gui_nick_group *group,
                                     const char *property,
                                     const char *value);

引数:

- buffer: バッファへのポインタ

- group: グループへのポインタ

- property: プロパティ名 (以下の表を参照)

- value: プロパティの新しい値

プロパティ:

名前 | Min WeeChat | 値 | 説明
--- | --- | --- | ---
id | 4.3.0 | long long integer ≥ 0 | New id for the group (it must be unique in the buffer). Note: it is not recommended to change this identifier.
color |  | WeeChat 色オプション名 | 関数 nicklist_add_group の引数 "color" を参照
visible |  | "0"、"1" | "0" = 非表示状態のグループ、"1" = 表示状態のグループ

C 言語での使用例:

    /* change group color to "bar_fg" */
    weechat_nicklist_group_set (buffer, group, "color", "bar_fg");

    /* change group color to yellow */
    weechat_nicklist_group_set (buffer, group, "color", "yellow");

    /* hide group in nicklist */
    weechat_nicklist_group_set (buffer, group, "visible", "0");

スクリプト (Python) での使用例:

    # プロトタイプ
    def nicklist_group_set(buffer: str, group: str, property: str, value: str) -> int: ...

    # 例

    # change group color to "bar_fg"
    weechat.nicklist_group_set(buffer, group, "color", "bar_fg")

    # change group color to yellow
    weechat.nicklist_group_set(buffer, group, "color", "yellow")

    # hide group in nicklist
    weechat.nicklist_group_set(buffer, group, "visible", "0")

#### nicklist_nick_get_integer

WeeChat バージョン 0.3.4 以上で利用可。

ニックネームプロパティの整数値を返す。

プロトタイプ:

    int weechat_nicklist_nick_get_integer (struct t_gui_buffer *buffer,
                                           struct t_gui_nick *nick,
                                           const char *property);

引数:

- buffer: バッファへのポインタ

- nick: ニックネームへのポインタ

- property: プロパティ名:

  - visible: 表示状態のニックネームの場合 1、それ以外の場合は 0

戻り値:

- プロパティの整数値

C 言語での使用例:

    int visible = weechat_nicklist_nick_get_integer (buffer, nick, "visible");

スクリプト (Python) での使用例:

    # プロトタイプ
    def nicklist_nick_get_integer(buffer: str, nick: str, property: str) -> int: ...

    # 例
    visible = weechat.nicklist_nick_get_integer(buffer, nick, "visible")

#### nicklist_nick_get_string

WeeChat バージョン 0.3.4 以上で利用可。

ニックネームプロパティの文字列値を返す。

プロトタイプ:

    const char *weechat_nicklist_nick_get_string (struct t_gui_buffer *buffer,
                                                  struct t_gui_nick *nick,
                                                  const char *property);

引数:

- buffer: バッファへのプロパティ

- nick: ニックネームへのポインタ

- property: プロパティ名:

  - id: unique identifier (WeeChat ≥ 4.3.0)

  - name: ニックネームの名前

  - color: ニックネームリスト内でのニックネームの色

  - prefix: ニックネームのプレフィックス

  - prefix_color: ニックネームリスト内でのプレフィックスの色

戻り値:

- プロパティの文字列値

C 言語での使用例:

    const char *color = weechat_nicklist_nick_get_string (buffer, nick, "color");

スクリプト (Python) での使用例:

    # プロトタイプ
    def nicklist_nick_get_string(buffer: str, nick: str, property: str) -> str: ...

    # 例
    color = weechat.nicklist_nick_get_string(buffer, nick, "color")

#### nicklist_nick_get_pointer

WeeChat バージョン 0.3.4 以上で利用可。

ニックネームプロパティのポインタ値を返す。

プロトタイプ:

    void *weechat_nicklist_nick_get_pointer (struct t_gui_buffer *buffer,
                                             struct t_gui_nick *nick,
                                             const char *property);

引数:

- buffer: バッファへのポインタ

- nick: ニックネームへのポインタ

- property: プロパティ名:

  - group: 指定したニックネームを含むグループへのポインタ

戻り値:

- プロパティのポインタ値

C 言語での使用例:

    struct t_gui_nick_group *group = weechat_nicklist_nick_get_pointer (buffer, nick, "group");

スクリプト (Python) での使用例:

    # プロトタイプ
    def nicklist_nick_get_pointer(buffer: str, nick: str, property: str) -> str: ...

    # 例
    group = weechat.nicklist_nick_get_pointer(buffer, nick, "group")

#### nicklist_nick_set

WeeChat ≥ 0.3.4, updated in 4.3.0.

ニックネームプロパティの文字列値を設定。

プロトタイプ:

    void weechat_nicklist_nick_set (struct t_gui_buffer *buffer,
                                    struct t_gui_nick *nick,
                                    const char *property,
                                    const char *value);

引数:

- buffer: バッファへのポインタ

- nick: ニックネームへのポインタ

- property: プロパティ名 (以下の表を参照)

- value: プロパティの新しい値

プロパティ:

名前 | Min WeeChat | 値 | 説明
--- | --- | --- | ---
id | 4.3.0 | long long integer ≥ 0 | New id for the nick (it must be unique in the buffer). Note: it is not recommended to change this identifier.
color |  | WeeChat 色オプション名 | 関数 nicklist_add_nick の引数 "color" を参照
prefix |  | 任意の文字列 | 指定したニックネームのプレフィックス
prefix_color |  | WeeChat color option name | 関数 nicklist_add_nick の引数 "prefix_color" を参照
visible |  | "0", "1" | "0" = 非表示状態のニックネーム、"1" = 表示状態のニックネーム

C 言語での使用例:

    /* change nick color to cyan */
    weechat_nicklist_nick_set (buffer, nick, "color", "cyan");

    /* change prefix to "+" */
    weechat_nicklist_nick_set (buffer, nick, "prefix", "+");

    /* change prefix color to yellow */
    weechat_nicklist_nick_set (buffer, nick, "prefix_color", "yellow");

    /* hide nick in nicklist */
    weechat_nicklist_nick_set (buffer, nick, "visible", "0");

スクリプト (Python) での使用例:

    # プロトタイプ
    def nicklist_nick_set(buffer: str, nick: str, property: str, value: str) -> int: ...

    # 例

    # change nick color to cyan
    weechat.nicklist_nick_set(buffer, nick, "color", "cyan")

    # change prefix to "+"
    weechat.nicklist_nick_set(buffer, nick, "prefix", "+")

    # change prefix color to yellow
    weechat.nicklist_nick_set(buffer, nick, "prefix_color", "yellow")

    # hide nick in nicklist
    weechat.nicklist_nick_set(buffer, nick, "visible", "0")

### 3.19. バー

バーを操作する関数。

#### bar_item_search

バー要素を検索。

プロトタイプ:

    struct t_gui_bar_item *weechat_bar_item_search (const char *name);

引数:

- name: バー要素の名前

戻り値:

- 見つかったバー要素へのポインタ、バー要素が見つからない場合 NULL

C 言語での使用例:

    struct t_gui_bar_item *bar_item = weechat_bar_item_search ("myitem");

スクリプト (Python) での使用例:

    # プロトタイプ
    def bar_item_search(name: str) -> str: ...

    # 例
    bar_item = weechat.bar_item_search("myitem")

#### bar_item_new

WeeChat バージョン 0.4.2 と 1.5 で更新。

新しいバー要素を作成。

プロトタイプ:

    struct t_gui_bar_item *weechat_bar_item_new (const char *name,
                                                 char *(*build_callback)(const void *pointer,
                                                                         void *data,
                                                                         struct t_gui_bar_item *item,
                                                                         struct t_gui_window *window,
                                                                         struct t_gui_buffer *buffer,
                                                                         struct t_hashtable *extra_info),
                                                 const void *build_callback_pointer,
                                                 void *build_callback_data);

引数:

- name: バー要素の名前

- build_callback: バー要素を作成する際に呼び出すコールバック関数、引数と戻り値:

  - const void *pointer: ポインタ

  - void *data: ポインタ

  - struct t_gui_bar_item *item: 要素へのポインタ

  - struct t_gui_window *window: ウィンドウへのポインタ (ルートバーの場合は NULL)

  - struct t_gui_buffer *buffer: ウィンドウに表示されているバッファ (ウィンドウが NULL の場合、現在のバッファ) または以下の構文で指定したバー要素に含まれるバッファ: "@buffer:item" (WeeChat バージョン 0.4.2 以上で利用可)

  - struct t_hashtable *extra_info: 常に NULL (この引数は将来のバージョン用に予約されています) (WeeChat バージョン 0.4.2 以上で利用可)

  - 戻り値: バー要素の内容

- build_callback_pointer: WeeChat が build_callback コールバックを呼び出す際にコールバックに渡すポインタ

- build_callback_data: WeeChat が build_callback コールバックを呼び出す際にコールバックに渡すポインタ このポインタが NULL でない場合、このポインタは malloc (または類似の関数) によって割り当てられたものでなければいけません。さらに、このポインタはここで作成したバー要素が削除された時点で自動的に開放されます

戻り値:

- バー要素へのポインタ、エラーが起きた場合は NULL

C 言語での使用例:

    char *
    my_build_callback (const void *pointer, void *data,
                       struct t_gui_bar_item *item,
                       struct t_gui_window *window,
                       struct t_gui_buffer *buffer,
                       struct t_hashtable *extra_info)
    {
        return strdup ("my content");
    }

    struct t_gui_bar_item *my_item = weechat_bar_item_new ("myitem",
                                                           &my_build_callback,
                                                           NULL, NULL);

スクリプト (Python) での使用例:

重要 | WeeChat バージョン 0.4.1 以下に対する互換性のために、デフォルトのコールバックに渡す引数の個数は 3 個です: data、item、window (buffer と extra_info は渡されません)。 全ての引数を受け取るコールバックを使う場合は、名前の前に "(extra)" をつけてください、以下の例を参照 (WeeChat バージョン 0.4.2 以上で利用可)。

    # プロトタイプ
    def bar_item_new(name: str, build_callback: str, build_callback_data: str) -> str: ...

    # 例 (コールバックに "buffer" と "extra_info" を除いた引数を渡す)
    def my_build_callback(data: str, item: str, window: str) -> str:
        return "my content"

    bar_item = weechat.bar_item_new("myitem", "my_build_callback", "")

    # 例 (コールバックに全ての引数を渡す、WeeChat バージョン 0.4.2 以上で利用可)
    def my_build_callback2(data: str, item: str, window: str, buffer: str, extra_info: Dict[str, str]) -> str:
        return "my content"

    bar_item2 = weechat.bar_item_new("(extra)myitem2", "my_build_callback2", "")  # WeeChat バージョン 0.4.2 以上で利用可

#### bar_item_update

build_callback コールバックを呼び出してバー要素の内容を更新。

プロトタイプ:

    void weechat_bar_item_update (const char *name);

引数:

- name: バー要素の名前

C 言語での使用例:

    weechat_bar_item_update ("myitem");

スクリプト (Python) での使用例:

    # プロトタイプ
    def bar_item_update(name: str) -> int: ...

    # 例
    weechat.bar_item_update("myitem")

#### bar_item_remove

バー要素を削除。

プロトタイプ:

    void weechat_bar_item_remove (struct t_gui_bar_item *item);

引数:

- item: バー要素へのポインタ

C 言語での使用例:

    weechat_bar_item_remove (&my_item);

スクリプト (Python) での使用例:

    # プロトタイプ
    def bar_item_remove(item: str) -> int: ...

    # 例
    weechat.bar_item_remove(myitem)

#### bar_search

バーを検索。

プロトタイプ:

    struct t_gui_bar *weechat_bar_search (const char *name);

引数:

- name: バーの名前

戻り値:

- 見つかったバーへのポインタ、見つからなかった場合は NULL

C 言語での使用例:

    struct t_gui_bar *bar = weechat_bar_search ("mybar");

スクリプト (Python) での使用例:

    # プロトタイプ
    def bar_search(name: str) -> str: ...

    # 例
    bar = weechat.bar_search("mybar")

#### bar_new

WeeChat バージョン 2.9, 4.0.0 で更新。

新しいバーを作成。

プロトタイプ:

    struct t_gui_bar *weechat_bar_new (const char *name,
                                       const char *hidden,
                                       const char *priority,
                                       const char *type,
                                       const char *condition,
                                       const char *position,
                                       const char *filling_top_bottom,
                                       const char *filling_left_right,
                                       const char *size,
                                       const char *size_max,
                                       const char *color_fg,
                                       const char *color_delim,
                                       const char *color_bg,
                                       const char *color_bg_inactive,
                                       const char *separator,
                                       const char *items);

引数:

- name: バーの名前

- hidden:

  - on: バーを非表示

  - off: バーを表示

- priority: バーの優先度 (整数)

- type:

  - root: ウィンドウの外に 1 回だけ表示されたバー

  - window: 各ウィンドウに表示されたバー

- condition: バーの表示位置:

  - active: アクティブウィンドウのみに表示されているバー

  - inactive: 非アクティブウィンドウのみに表示されているバー

  - nicklist: ニックネームリストを持つウィンドウに表示されているバー

  - 評価された式: WeeChat ユーザーズガイド / バー状態 ↗を参照してください

- position: top、bottom、left、right

- filling_top_bottom:

  - horizontal: 要素は水平方向に詰め込まれている (各要素の後に間隔)

  - vertical: 要素は垂直方向に詰め込まれている (各要素の後に行)

  - columns_horizontal: 要素は水平方向に詰め込まれている、列と一緒に表示

  - columns_vertical: 要素は垂直方向に詰め込まれている、列と一緒に表示

- filling_left_right:

  - horizontal: 要素は水平方向に詰め込まれている (各要素の後に間隔)

  - vertical: 要素は垂直方向に詰め込まれている (各要素の後に行)

  - columns_horizontal: 要素は水平方向に詰め込まれている、列と一緒に表示

  - columns_vertical: 要素は垂直方向に詰め込まれている、列と一緒に表示

- size: バーのサイズ、文字単位 (0 は自動サイズ)

- size_max: バーの最大サイズ (0 は最大サイズが指定されていない)

- color_fg: バーのテキスト色

- color_bg_inactive: background color for window bar which is not displayed in active window

- color_delim: バーの区切り文字の色

- color_bg: バーの背景色

- separator:

  - on: バーには他のウィンドウおよびバーとの区切り行がある

  - off: 区切り無し

- items: バーの要素のリスト、コンマ (要素の間に間隔)、または "+" (要素の間に間隔を開けない) 区切り

戻り値:

- 新しいバーへのポインタ、エラーが起きた場合は NULL

注記 | Since version 4.0.0, if the bar already exists, WeeChat sets the values received as default values for bar options and returns the bar pointer instead of NULL.

C 言語での使用例:

    struct t_gui_bar *my_bar = weechat_bar_new (
        "mybar", "off", "100", "window", "", "top", "horizontal", "vertical",
        "0", "5", "default", "cyan", "blue", "darkgray", "off",
        "time,buffer_number+buffer_name");

スクリプト (Python) での使用例:

    # プロトタイプ
    def bar_new(name: str, hidden: str, priority: str, type: str, condition: str, position: str,
                filling_top_bottom: str, filling_left_right: str, size: str, size_max: str,
                color_fg: str, color_delim: str, color_bg: str, color_bg_inactive: str,
                separator: str, items: str) -> str: ...

    # 例
    bar = weechat.bar_new("mybar", "off", "100", "window", "", "top", "horizontal", "vertical",
        "0", "5", "default", "cyan", "blue", "darkgray", "off", "time,buffer_number+buffer_name")

注記 | With WeeChat ≥ 2.9, in Ruby, the 4 colors (color_fg, color_delim, color_bg, color_bg_inactive) must be given in an array of 4 strings (due to a Ruby limitation of 15 arguments by function), see the WeeChat scripting guide ↗ for more info.

#### bar_set

バープロパティに新しい値を設定。

プロトタイプ:

    int weechat_bar_set (struct t_gui_bar *bar, const char *property,
                         const char *value);

引数:

- bar: バーへのポインタ

- property: name、hidden、priority、conditions、position、filling_top_bottom、filling_left_right、size、size_max、color_fg、color_delim、color_bg、separator、items (bar_new を参照)

- value: プロパティの新しい値

戻り値:

- 新しい値を設定した場合は 1、エラーが起きた場合は 0

C 言語での使用例:

    weechat_bar_set (mybar, "position", "bottom");

スクリプト (Python) での使用例:

    # プロトタイプ
    def bar_set(bar: str, property: str, value: str) -> int: ...

    # 例
    weechat.bar_set(my_bar, "position", "bottom")

#### bar_update

画面上のバーの内容を更新。

プロトタイプ:

    void weechat_bar_update (const char *name);

引数:

- name: バーの名前

C 言語での使用例:

    weechat_bar_update ("mybar");

スクリプト (Python) での使用例:

    # プロトタイプ
    def bar_update(name: str) -> int: ...

    # 例
    weechat.bar_update("mybar")

#### bar_remove

バーを削除。

プロトタイプ:

    void weechat_bar_remove (struct t_gui_bar *bar);

引数:

- bar: バーへのポインタ

C 言語での使用例:

    weechat_bar_remove (mybar);

スクリプト (Python) での使用例:

    # プロトタイプ
    def bar_remove(bar: str) -> int: ...

    # 例
    weechat.bar_remove(my_bar)

### 3.20. コマンド

WeeChat コマンドを実行する関数。

#### command

Updated in 1.1, 4.0.0.

コマンドを実行するか、バッファにテキストを送信。

プロトタイプ:

    int weechat_command (struct t_gui_buffer *buffer, const char *command);

引数:

- buffer: バッファへのポインタ (コマンドは指定したバッファで実行されます、現在のバッファで実行するには NULL を指定してください)

- command: 実行するコマンド ("/" で始まっている場合)、またはバッファに送信するテキスト

注記 | On buffer with `input_multiline` set to `0` (default), only the first command is executed (before the first newline char: `\n`).

戻り値 (WeeChat バージョン 1.1 以上で利用可):

- WEECHAT_RC_OK 成功した場合

- WEECHAT_RC_ERROR エラーが起きた場合

C 言語での使用例:

    int rc;
    rc = weechat_command (weechat_buffer_search ("irc", "libera.#weechat"),
                          "/whois FlashCode");

スクリプト (Python) での使用例:

    # プロトタイプ
    def command(buffer: str, command: str) -> int: ...

    # 例
    rc = weechat.command(weechat.buffer_search("irc", "libera.#weechat"), "/whois FlashCode")

#### command_options

WeeChat ≥ 2.5, updated in 4.0.0, 4.5.0.

バッファにてオプション付きでコマンドを実行またはテキストを送信

プロトタイプ:

    int weechat_command_options (struct t_gui_buffer *buffer, const char *command,
                                 struct t_hashtable *options);

引数:

- buffer: バッファへのポインタ (コマンドは指定したバッファで実行されます、現在のバッファで実行するには NULL を指定してください)

- command: 実行するコマンド (if beginning with a `/` or a command char)、またはバッファに送信するテキスト

- options: オプションを含むハッシュテーブル (キーと値は文字列です) (NULL は使えません):

- options: a hashtable with some options (keys and values must be string) (can be NULL):

  - commands: 指定したコマンドの中で実行を許可するコマンドのカンマ区切りリスト、リストの書式は関数 string_match_list を参考にしてください; the special value `-` (hyphen-minus) disables the execution of commands and the string in command is sent as-is to the buffer (WeeChat ≥ 4.5.0)

  - delay: コマンド実行までの遅延時間、ミリ秒単位

  - split_newline: `1` to split commands on newline char (`\n`) (WeeChat ≥ 4.0.0)

戻り値:

- WEECHAT_RC_OK 成功した場合

- WEECHAT_RC_ERROR エラーが起きた場合

C 言語での使用例:

    /* /exec 以外のコマンド実行を許可、2 秒後にコマンドを実行 */
    int rc;
    struct t_hashtable *options = weechat_hashtable_new (8,
                                                         WEECHAT_HASHTABLE_STRING,
                                                         WEECHAT_HASHTABLE_STRING,
                                                         NULL,
                                                         NULL);
    weechat_hashtable_set (options, "commands", "*,!exec");
    weechat_hashtable_set (options, "delay", "2000");
    rc = weechat_command_options (NULL, "/some_command arguments", options);

スクリプト (Python) での使用例:

    # プロトタイプ
    def command_options(buffer: str, command: str, options: Dict[str, str]) -> int: ...

    # 例: /exec 以外のコマンド実行を許可
    rc = weechat.command_options("", "/some_command arguments", {"commands": "*,!exec", "delay": "2000"})

### 3.21. Completion

Functions to complete a command line.

#### completion_new

WeeChat ≥ 2.9.

Create a new completion.

プロトタイプ:

    struct t_gui_completion *weechat_completion_new (struct t_gui_buffer *buffer);

引数:

- buffer: buffer pointer

Return value:

- pointer to new completion

C 言語での使用例:

    struct t_gui_completion *completion = weechat_completion_new (weechat_buffer_search_main ());

スクリプト (Python) での使用例:

    # プロトタイプ
    def completion_new(buffer: str) -> str: ...

    # 例
    completion = weechat.completion_new(weechat.buffer_search_main())

#### completion_search

WeeChat ≥ 2.9.

Search possible words at a given position of a string, in the completion context.

プロトタイプ:

    int weechat_completion_search (struct t_gui_completion *completion, const char *data,
                                   int position, int direction);

引数:

- completion: completion pointer

- data: the string to complete

- position: index of the char in string to complete (starts to 0)

- direction: 1 for next completion, -1 for previous completion

戻り値:

- 成功した場合は 1、失敗した場合は 0

C 言語での使用例:

    struct t_gui_completion *completion = weechat_completion_new (weechat_buffer_search_main ());
    if (weechat_completion_search (completion, "/help filt", 10, 1))
    {
        /* ... */
    }

スクリプト (Python) での使用例:

    # プロトタイプ
    def completion_search(completion: str, data: str, position: int, direction: int) -> int: ...

    # 例
    completion = weechat.completion_new(weechat.buffer_search_main())
    if weechat.completion_search(completion, "/help filt", 10, 1):
        # ...

#### completion_get_string

WeeChat バージョン 2.9 以上で利用可。

補完プロパティを文字列で取得。

プロトタイプ:

    const char *weechat_completion_get_string (struct t_gui_completion *completion,
                                               const char *property);

引数:

- completion: 補完へのポインタ

- property: プロパティ名:

  - base_command: 補完に使ったコマンド

  - base_word: 補完された単語

  - args: コマンド引数 (元の単語を含む)

C 言語での使用例:

    int
    my_completion_cb (const void *pointer, void *data, const char *completion_item,
                      struct t_gui_buffer *buffer,
                      struct t_gui_completion *completion)
    {
        /* get arguments of command */
        const char *args = weechat_completion_get_string (completion, "args");

        /* completion depending on args */
        /* ... */

        return WEECHAT_RC_OK;
    }

スクリプト (Python) での使用例:

    # プロトタイプ
    def completion_get_string(completion: str, property: str) -> str: ...

    # 例
    def my_completion_cb(data: str, completion_item: str, buffer: str, completion: str) -> int:
        # get arguments of command
        args = weechat.completion_get_string(completion, "args")
        # completion depending on args
        # ...
        return weechat.WEECHAT_RC_OK

#### completion_set

WeeChat バージョン 4.6.0 以上で利用可。

Set a completion property.

プロトタイプ:

    void weechat_completion_get_string (struct t_gui_completion *completion,
                                        const char *property,
                                        const char *value);

引数:

- completion: 補完へのポインタ

- property: プロパティ名 (以下の表を参照)

- value: プロパティの新しい値

プロパティ:

Name | Min WeeChat | Value | Description
--- | --- | --- | ---
add_space | 4.6.0 | "0" or "1" | "0": do not add space after completion "1": add space after completion (default).

C 言語での使用例:

    int
    my_completion_cb (const void *pointer, void *data, const char *completion_item,
                      struct t_gui_buffer *buffer,
                      struct t_gui_completion *completion)
    {
        /* do not add space after completion */
        weechat_completion_set (completion, "add_space", "0");

        /* ... */

        return WEECHAT_RC_OK;
    }

スクリプト (Python) での使用例:

    # prototype
    def completion_set(completion: str, property: str, value: str) -> int: ...

    # example
    def my_completion_cb(data: str, completion_item: str, buffer: str, completion: str) -> int:
        # do not add space after completion
        weechat.completion_set(completion, "add_space", "0")
        # ...
        return weechat.WEECHAT_RC_OK

#### completion_list_add

WeeChat バージョン 2.9 以上で利用可。

補完用に単語を追加。

プロトタイプ:

    void weechat_completion_list_add (struct t_gui_completion *completion,
                                      const char *word,
                                      int nick_completion,
                                      const char *where);

引数:

- completion: 補完へのポインタ

- word: 追加する単語

- nick_completion: 単語がニックネームの場合は 1、そうでなければ 0

- where: 単語を追加するリスト上での位置:

  - WEECHAT_LIST_POS_SORT: リストがソートされた状態になるような位置

  - WEECHAT_LIST_POS_BEGINNING: リストの最初

  - WEECHAT_LIST_POS_END: リストの最後

C 言語での使用例: hook_completion を参照。

スクリプト (Python) での使用例:

    # プロトタイプ
    def completion_list_add(completion: str, word: str, nick_completion: int, where: str) -> int: ...

    # 例: see function hook_completion

#### completion_free

WeeChat ≥ 2.9.

Free a completion.

プロトタイプ:

    void weechat_completion_free (struct t_gui_completion *completion);

引数:

- completion: completion pointer

C 言語での使用例:

    weechat_completion_free (completion);

スクリプト (Python) での使用例:

    # プロトタイプ
    def completion_free(completion: str) -> int: ...

    # 例
    weechat.completion_free(completion)

### 3.22. ネットワーク

ネットワーク関数。

#### network_pass_proxy

プロキシへの接続および認証を確立する。

重要 | この関数は connect() の呼び出しを遮断します、このため connect() を呼び出す場合は WeeChat がこれを遮断しないように必ずフォークしたプロセスの中で行ってください。

プロトタイプ:

    int weechat_network_pass_proxy (const char *proxy,
                                    int sock,
                                    const char *address,
                                    int port);

引数:

- proxy: 使用するプロキシ名

- sock: 使用するソケット

- address: アドレス (ホスト名または IP アドレス)

- port: ポート番号

戻り値:

- 接続が確立された場合は 1、エラーが起きた場合は 0

C 言語での使用例:

    if (weechat_network_pass_proxy ("my_proxy", sock, "irc.libera.chat", 6667))
    {
        /* OK */
    }
    else
    {
        /* error */
    }

注記 | スクリプト API ではこの関数を利用できません。

#### network_connect_to

WeeChat バージョン 0.4.3 で更新。

リモートホストとの接続を確立する。

重要 | この関数は connect() の呼び出しを遮断します、このため connect() を呼び出す場合は WeeChat がこれを遮断しないように必ずフォークしたプロセスの中で行ってください。

プロトタイプ:

    int weechat_network_connect_to (const char *proxy,
                                    struct sockaddr *address,
                                    socklen_t address_length);

引数:

- proxy: 使用するプロキシ名

- address: 接続先のアドレス (ポート番号を含む)

- address_length: 引数 address の長さ

戻り値:

- 接続が確立した場合はソケット番号 (≥ 0)、エラーが起きた場合は -1

C 言語での使用例:

    struct sockaddr *addr;
    socklen_t length;
    int sock;

    /* allocate/set address and port in _addr_, set _length_ */
    /* ... */

    sock = weechat_network_connect_to (NULL, addr, length);
    if (sock >= 0)
    {
        /* OK */
    }
    else
    {
        /* error */
    }

注記 | スクリプト API ではこの関数を利用できません。

### 3.23. インフォ

インフォを取得する関数。

#### info_get

WeeChat バージョン 2.5 で更新。

文字列型で WeeChat またはプラグインからのインフォを返す。

プロトタイプ:

    char *weechat_info_get (const char *info_name, const char *arguments);

引数:

- info_name: 読み出すインフォの名前 (以下の表を参照)

- arguments: 指定したインフォに対する引数 (任意、引数を指定しない場合は NULL)

戻り値:

- 指定したインフォを含む文字列、エラーが起きた場合は NULL (使用後には必ず "free" を呼び出して領域を開放してください)

注記 | WeeChat バージョン 2.5 以上の場合、返却される値は確保された文字列です (WeeChat バージョン 2.4 以下の場合、返却される値は定数文字列へのポインタです)。

インフォ:

Plugin | Name | Description | Arguments
--- | --- | --- | ---
fifo | fifo_filename | name of FIFO pipe | -
guile | guile_eval | evaluation of source code | source code to execute
guile | guile_interpreter | name of the interpreter used | -
guile | guile_version | version of the interpreter used | -
irc | irc_buffer | get buffer pointer for an IRC server/channel/nick | server,channel,nick (channel and nicks are optional)
irc | irc_is_channel | 1 if string is a valid IRC channel name for server | server,channel (server is optional)
irc | irc_is_message_ignored | 1 if the nick is ignored (message is not displayed) | server,message (message is the raw IRC message)
irc | irc_is_nick | 1 if string is a valid IRC nick name | server,nickname (server is optional)
irc | irc_nick | get current nick on a server | server name
irc | irc_nick_color | get nick color code (deprecated since version 1.5, replaced by "nick_color") | nickname
irc | irc_nick_color_name | get nick color name (deprecated since version 1.5, replaced by "nick_color_name") | nickname
irc | irc_nick_from_host | get nick from IRC host | IRC host (like `:nick!name@server.com`)
irc | irc_ptr_channel | get pointer to an IRC channel | server,channel
irc | irc_ptr_nick | get pointer to an IRC nick | server,channel,nick
irc | irc_ptr_server | get pointer to an IRC server | server
irc | irc_server_cap | 1 if capability is enabled in server | server,capability
irc | irc_server_cap_value | value of capability, if enabled in server | server,capability
irc | irc_server_isupport | 1 if server supports this feature (from IRC message 005) | server,feature
irc | irc_server_isupport_value | value of feature, if supported by server (from IRC message 005) | server,feature
logger | logger_log_file | path to current log filename for the buffer | buffer pointer ("0x12345678") or buffer full name ("irc.libera.#weechat")
lua | lua_eval | evaluation of source code | source code to execute
lua | lua_interpreter | name of the interpreter used | -
lua | lua_version | version of the interpreter used | -
perl | perl_eval | evaluation of source code | source code to execute
perl | perl_interpreter | name of the interpreter used | -
perl | perl_version | version of the interpreter used | -
php | php_eval | evaluation of source code | source code to execute
php | php_interpreter | name of the interpreter used | -
php | php_version | version of the interpreter used | -
python | python_eval | evaluation of source code | source code to execute
python | python_interpreter | name of the interpreter used | -
python | python_version | version of the interpreter used | -
relay | relay_api_version | relay API version | -
relay | relay_api_version_number | relay API version (as number) | -
relay | relay_client_count | number of clients for relay | protocol,status (both are optional, for each argument "*" means all; protocols: irc, weechat; statuses: connecting, waiting_auth, connected, auth_failed, disconnected)
ruby | ruby_eval | evaluation of source code | source code to execute
ruby | ruby_interpreter | name of the interpreter used | -
ruby | ruby_version | version of the interpreter used | -
script | script_info | info on a script | script,info (script name with extension and info is a hdata variable
script | script_loaded | 1 if script is loaded | script name with extension
spell | spell_dict | comma-separated list of dictionaries used in buffer | buffer pointer ("0x12345678") or buffer full name ("irc.libera.#weechat")
tcl | tcl_eval | evaluation of source code | source code to execute
tcl | tcl_interpreter | name of the interpreter used | -
tcl | tcl_version | version of the interpreter used | -
weechat | auto_connect | 1 if automatic connection to servers is enabled, 0 if it has been disabled by the user (option "-a" or "--no-connect") | -
weechat | auto_load_scripts | 1 if scripts are automatically loaded, 0 if the auto-load has been disabled by the user (option "-s" or "--no-script") | -
weechat | buffer | buffer pointer | buffer full name
weechat | charset_internal | WeeChat internal charset | -
weechat | charset_terminal | terminal charset | -
weechat | color_ansi_regex | POSIX extended regular expression to search ANSI escape codes | -
weechat | color_rgb2term | RGB color converted to terminal color (0-255) | rgb,limit (limit is optional and is set to 256 by default)
weechat | color_term2rgb | terminal color (0-255) converted to RGB color | color (terminal color: 0-255)
weechat | cursor_mode | 1 if cursor mode is enabled | -
weechat | date | WeeChat compilation date/time | -
weechat | dir_separator | directory separator | -
weechat | filters_enabled | 1 if filters are enabled | -
weechat | inactivity | keyboard inactivity (seconds) | -
weechat | locale | locale used for translating messages | -
weechat | mouse | 1 if mouse is enabled | -
weechat | nick_color | get nick color code | nickname;colors (colors is an optional comma-separated list of colors to use; background is allowed for a color with format text:background; if colors is present, WeeChat options with nick colors and forced nick colors are ignored)

weechat

nick_color_ignore_case

get nick color code, ignoring case

nickname;range;colors (range is a number of chars (see function strcasecmp_range, 0 = convert to lower case without using a range), colors is an optional comma-separated list of colors to use; background is allowed for a color with format text:background; if colors is present, WeeChat options with nick colors and forced nick colors are ignored)

weechat | nick_color_name | get nick color name | nickname;colors (colors is an optional comma-separated list of colors to use; background is allowed for a color with format text:background; if colors is present, WeeChat options with nick colors and forced nick colors are ignored)

weechat

nick_color_name_ignore_case

get nick color name, ignoring case

nickname;range;colors (range is a number of chars (see function strcasecmp_range, 0 = convert to lower case without using a range), colors is an optional comma-separated list of colors to use; background is allowed for a color with format text:background; if colors is present, WeeChat options with nick colors and forced nick colors are ignored)

weechat | pid | WeeChat PID (process ID) | -
weechat | plugin_loaded | 1 if plugin is loaded | plugin name
weechat | term_color_pairs | number of color pairs supported in terminal | -
weechat | term_colors | number of colors supported in terminal | -
weechat | term_height | height of terminal | -
weechat | term_width | width of terminal | -
weechat | totp_generate | generate a Time-based One-Time Password (TOTP) | secret (in base32), timestamp (optional, current time by default), number of digits (optional, between 4 and 10, 6 by default)
weechat | totp_validate | validate a Time-based One-Time Password (TOTP): 1 if TOTP is correct, otherwise 0 | secret (in base32), one-time password, timestamp (optional, current time by default), number of passwords before/after to test (optional, 0 by default)
weechat | uptime | WeeChat uptime (format: "days:hh:mm:ss") | "days" (number of days) or "seconds" (number of seconds) (optional)
weechat | uptime_current | WeeChat uptime for the current process only (upgrades with /upgrade command are ignored) (format: "days:hh:mm:ss") | "days" (number of days) or "seconds" (number of seconds) (optional)
weechat | version | WeeChat version | -
weechat | version_git | WeeChat git version (output of command "git describe" for a development version only, empty for a stable release) | -
weechat | version_number | WeeChat version (as number) | version (optional, by default the version of the running WeeChat is returned)
weechat | weechat_cache_dir | WeeChat cache directory | -
weechat | weechat_config_dir | WeeChat config directory | -
weechat | weechat_daemon | 1 if WeeChat is running in daemon mode (headless, in background) | -
weechat | weechat_data_dir | WeeChat data directory | -
weechat | weechat_dir | WeeChat directory (deprecated since version 3.2, replaced by "weechat_config_dir", "weechat_data_dir", "weechat_state_dir" , "weechat_cache_dir" and "weechat_runtime_dir") | -
weechat | weechat_headless | 1 if WeeChat is running headless | -
weechat | weechat_libdir | WeeChat "lib" directory | -
weechat | weechat_localedir | WeeChat "locale" directory | -
weechat | weechat_runtime_dir | WeeChat runtime directory | -
weechat | weechat_sharedir | WeeChat "share" directory | -
weechat | weechat_site | WeeChat site | -
weechat | weechat_site_download | WeeChat site, download page | -
weechat | weechat_state_dir | WeeChat state directory | -
weechat | weechat_upgrading | 1 if WeeChat is upgrading (command `/upgrade`) | -
weechat | window | window pointer | window number

C 言語での使用例:

    char *version = weechat_info_get ("version", NULL);
    char *date = weechat_info_get ("date", NULL);
    weechat_printf (NULL, "Current WeeChat version is: %s (compiled on %s)",
                    version, date);
    if (version)
        free (version);
    if (date)
        free (date);

    char *weechat_config_dir = weechat_info_get ("weechat_config_dir", NULL);
    weechat_printf (NULL, "WeeChat config directory is: %s", weechat_config_dir);
    if (weechat_config_dir)
        free (weechat_config_dir);

スクリプト (Python) での使用例:

    # プロトタイプ
    def info_get(info_name: str, arguments: str) -> str: ...

    # 例
    weechat.prnt("", "Current WeeChat version is: %s (compiled on %s)"
        % (weechat.info_get("version", ""), weechat.info_get("date", ""))
    weechat.prnt("", "WeeChat config directory is: %s" % weechat.info_get("weechat_config_dir", ""))

#### info_get_hashtable

WeeChat バージョン 0.3.4 以上で利用可。

ハッシュテーブルで WeeChat またはプラグインからのインフォを返す。

プロトタイプ:

    struct t_hashtable *weechat_info_get_hashtable (const char *info_name,
                                                    struct t_hashtable *hashtable);

引数:

- info_name: 読み出すインフォの名前 (以下の表を参照)

- hashtable: 引数を含むハッシュテーブル (指定したインフォに依存) (任意、引数を指定しない場合は NULL)

戻り値:

- 指定したインフォを含むハッシュテーブル、エラーが起きた場合は NULL (must be freed by calling hashtable_free after use)

インフォ:

Plugin | Name | Description | Hashtable (input) | Hashtable (output)
--- | --- | --- | --- | ---

irc

irc_message_parse

parse an IRC message

"message": IRC message, "server": server name (optional)

"tags": tags, "tag_xxx": unescaped value of tag "xxx" (one key per tag), "message_without_tags": message without the tags, "nick": nick, "user": user, "host": host, "command": command, "channel": channel, "arguments": arguments (includes channel), "text": text (for example user message), "param1" …​ "paramN": parsed command parameters, "num_params": number of parsed command parameters, "pos_command": index of "command" message ("-1" if "command" was not found), "pos_arguments": index of "arguments" message ("-1" if "arguments" was not found), "pos_channel": index of "channel" message ("-1" if "channel" was not found), "pos_text": index of "text" message ("-1" if "text" was not found)

irc | irc_message_split | split an IRC message (to fit in 512 bytes by default) | "message": IRC message, "server": server name (optional) | "msg1" …​ "msgN": messages to send (without final "\r\n"), "args1" …​ "argsN": arguments of messages, "count": number of messages
weechat | focus_info | get focus info | "x": x coordinate (string with integer >= 0), "y": y coordinate (string with integer >= 0) | see function "hook_focus" in Plugin API reference
weechat | secured_data | secured data | - | secured data: names and values (be careful: the values are sensitive data: do NOT print/log them anywhere)

C 言語での使用例:

    struct t_hashtable *hashtable_in, *hashtable_out;

    hashtable_in = weechat_hashtable_new (8,
                                          WEECHAT_HASHTABLE_STRING,
                                          WEECHAT_HASHTABLE_STRING,
                                          NULL,
                                          NULL);
    if (hashtable_in)
    {
        weechat_hashtable_set (
            hashtable_in,
            "message",
            "@time=2015-06-27T16:40:35.000Z;tag2=value\\sspace :nick!user@host PRIVMSG #weechat :Hello world!");
        hashtable_out = weechat_info_get_hashtable ("irc_message_parse",
                                                    hashtable_in);
        /*
         * now hashtable_out has following keys/values:
         *   "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 :Hello world!"
         *   "nick"                : "nick"
         *   "user"                : "user"
         *   "host"                : "nick!user@host"
         *   "command"             : "PRIVMSG"
         *   "channel"             : "#weechat"
         *   "arguments"           : "#weechat :Hello world!"
         *   "text"                : "Hello world!"
         *   "param1"              : "#weechat"
         *   "param2"              : "Hello world!"
         *   "num_params"          : "2"
         *   "pos_command"         : "65"
         *   "pos_arguments"       : "73"
         *   "pos_channel"         : "73"
         *   "pos_text"            : "83"
         */
        weechat_hashtable_free (hashtable_in);
        weechat_hashtable_free (hashtable_out);
    }

注記 | "irc_message_parse" の出力に関するより詳しい情報は WeeChat スクリプト作成ガイド / メッセージの構文解析 ↗を参照してください。

スクリプト (Python) での使用例:

    # プロトタイプ
    def info_get_hashtable(info_name: str, dict_in: Dict[str, str]) -> Dict[str, str]: ...

    # 例
    dict_in = {"message": ":nick!user@host PRIVMSG #weechat :message here"}
    weechat.prnt("", "message parsed: %s"
                 % weechat.info_get_hashtable("irc_message_parse", dict_in))

### 3.24. インフォリスト

インフォリストは「要素」の配列であり、各要素には変数が含まれています。

例えば、インフォリスト "irc_server" には N 個 (N は定義済みの IRC サーバの数) の要素が含まれています。それぞれの要素には "name"、"buffer"、"is_connected" などの変数が含まれています。

各要素には型と値があり、以下の型を使うことができます:

- integer: 任意の整数値

- string: 任意の文字列値

- pointer: 任意のポインタ

- buffer: 任意のデータを含む固定長のバッファ

- time: 時刻値

#### infolist_new

新しいインフォリストを作成。

プロトタイプ:

    struct t_infolist *weechat_infolist_new ();

戻り値:

- 新しいインフォリストへのポインタ

C 言語での使用例:

    struct t_infolist *infolist = weechat_infolist_new ();

スクリプト (Python) での使用例:

    # プロトタイプ
    def infolist_new() -> str: ...

    # 例
    infolist = weechat.infolist_new()

#### infolist_new_item

インフォリストに要素を追加。

プロトタイプ:

    struct t_infolist_item *weechat_infolist_new_item (struct t_infolist *infolist);

引数:

- infolist: インフォリストへのポインタ

戻り値:

- 新しい要素へのポインタ

C 言語での使用例:

    struct t_infolist_item *item = weechat_infolist_new_item (infolist);

スクリプト (Python) での使用例:

    # プロトタイプ
    def infolist_new_item(infolist: str) -> str: ...

    # 例
    item = weechat.infolist_new_item(infolist)

#### infolist_new_var_integer

インフォリストの要素に整数変数を追加。

プロトタイプ:

    struct t_infolist_var *weechat_infolist_new_var_integer (struct t_infolist_item *item,
                                                             const char *name,
                                                             int value);

引数:

- item: インフォリストの要素へのポインタ

- name: 変数名

- value: 整数値

戻り値:

- 新しい値へのポインタ

C 言語での使用例:

    struct t_infolist_var *var = weechat_infolist_new_var_integer (item,
                                                                   "my_integer",
                                                                   123);

スクリプト (Python) での使用例:

    # プロトタイプ
    def infolist_new_var_integer(item: str, name: str, value: int) -> str: ...

    # 例
    var = weechat.infolist_new_var_integer(item, "my_integer", 123)

#### infolist_new_var_string

インフォリストの要素に文字列変数を追加。

プロトタイプ:

    struct t_infolist_var *weechat_infolist_new_var_string (struct t_infolist_item *item,
                                                            const char *name,
                                                            const char *value);

引数:

- item: インフォリストの要素へのポインタ

- name: 変数名

- value: 文字列値

戻り値:

- 新しい値へのポインタ

C 言語での使用例:

    struct t_infolist_var *var = weechat_infolist_new_var_string (item,
                                                                  "my_string",
                                                                  "value");

スクリプト (Python) での使用例:

    # プロトタイプ
    def infolist_new_var_string(item: str, name: str, value: str) -> str: ...

    # 例
    var = weechat.infolist_new_var_string(item, "my_string", "value")

#### infolist_new_var_pointer

インフォリストの要素にポインタ変数を追加。

プロトタイプ:

    struct t_infolist_var *weechat_infolist_new_var_pointer (struct t_infolist_item *item,
                                                             const char *name,
                                                             void *pointer);

引数:

- item: インフォリストの要素へのポインタ

- name: 変数名

- pointer: ポインタ

戻り値:

- 新しい値へのポインタ

C 言語での使用例:

    struct t_infolist_var *var = weechat_infolist_new_var_pointer (item,
                                                                   "my_pointer",
                                                                   &pointer);

スクリプト (Python) での使用例:

    # プロトタイプ
    def infolist_new_var_pointer(item: str, name: str, pointer: str) -> str: ...

    # 例
    var = weechat.infolist_new_var_pointer(item, "my_pointer", pointer)

#### infolist_new_var_buffer

インフォリストの要素にバッファ変数を追加。

プロトタイプ:

    struct t_infolist_var *weechat_infolist_new_var_buffer (struct t_infolist_item *item,
                                                            const char *name,
                                                            void *pointer,
                                                            int size);

引数:

- item: インフォリストの要素へのポインタ

- name: 変数名

- pointer: バッファへのポインタ

- size: バッファのサイズ

戻り値:

- 新しい値へのポインタ

C 言語での使用例:

    char buffer[256];
    /* ... */
    struct t_infolist_var *var = weechat_infolist_new_var_buffer (item,
                                                                  "my_buffer",
                                                                  &buffer,
                                                                  sizeof (buffer));

注記 | スクリプト API ではこの関数を利用できません。

#### infolist_new_var_time

インフォリストの要素に時刻変数を追加。

プロトタイプ:

    struct t_infolist_var *weechat_infolist_new_var_time (struct t_infolist_item *item,
                                                          const char *name,
                                                          time_t time);

引数:

- item: インフォリストの要素へのポインタ

- name: 変数名

- time: 時刻値

戻り値:

- 新しい値へのポインタ

C 言語での使用例:

    struct t_infolist_var *var = weechat_infolist_new_var_time (item,
                                                                "my_time",
                                                                time (NULL));

スクリプト (Python) での使用例:

    # プロトタイプ
    def infolist_new_var_time(item: str, name: str, time: int) -> str: ...

    # 例
    var = weechat.infolist_new_var_time(item, "my_time", int(time.time()))

#### infolist_get

WeeChat またはプラグインからインフォリストを返す。

重要 | インフォリストの内容は実データの複製です。そのため多くのデータを含むインフォリスト ("buffer_lines" など) を要求した場合、WeeChat は全てのデータを複製するのに必要なメモリを確保し、これにはある程度時間がかかります。 大きなインフォリストを使う代わりに、hdata を使うほうが望ましいです (ただしインフォリストは生データである hdata よりも多くの情報を含む場合があります)、hdata を参照してください。

プロトタイプ:

    struct t_infolist *weechat_infolist_get (const char *infolist_name,
                                             void *pointer,
                                             const char *arguments);

引数:

- infolist_name: 読み出すインフォリストの名前 (以下の表を参照)

- pointer: 要素へのポインタ、インフォリストからこの要素のみを取得する場合に指定 (任意、NULL でも可)

- arguments: 指定したインフォリストに対する引数 (任意、引数が不要の場合は NULL)

戻り値:

- インフォリストへのポインタ、エラーが起きた場合は NULL

インフォリスト:

Plugin | Name | Description | Pointer | Arguments
--- | --- | --- | --- | ---
alias | alias | list of aliases | alias pointer (optional) | alias name (wildcard "*" is allowed) (optional)
alias | alias_default | list of default aliases | - | -
buflist | buflist | list of buffers in a buflist bar item | - | buflist bar item name (optional)
fset | fset_option | list of fset options | fset option pointer (optional) | option name (wildcard "*" is allowed) (optional)
guile | guile_script | list of scripts | script pointer (optional) | script name (wildcard "*" is allowed) (optional)
irc | irc_channel | list of channels for an IRC server | channel pointer (optional) | server,channel (channel is optional)
irc | irc_color_weechat | mapping between IRC color codes and WeeChat color names | - | -
irc | irc_ignore | list of IRC ignores | ignore pointer (optional) | -
irc | irc_modelist | list of channel mode lists for an IRC channel | mode list pointer (optional) | server,channel,type (type is optional)
irc | irc_modelist_item | list of items in a channel mode list | mode list item pointer (optional) | server,channel,type,number (number is optional)
irc | irc_nick | list of nicks for an IRC channel | nick pointer (optional) | server,channel,nick (nick is optional)
irc | irc_notify | list of notify | notify pointer (optional) | server name (wildcard "*" is allowed) (optional)
irc | irc_server | list of IRC servers | server pointer (optional) | server name (wildcard "*" is allowed) (optional)
logger | logger_buffer | list of logger buffers | logger pointer (optional) | -
lua | lua_script | list of scripts | script pointer (optional) | script name (wildcard "*" is allowed) (optional)
perl | perl_script | list of scripts | script pointer (optional) | script name (wildcard "*" is allowed) (optional)
php | php_script | list of scripts | script pointer (optional) | script name (wildcard "*" is allowed) (optional)
python | python_constant | list of scripting API constants | - | -
python | python_function | list of scripting API functions | - | -
python | python_script | list of scripts | script pointer (optional) | script name (wildcard "*" is allowed) (optional)
relay | relay | list of relay clients | relay pointer (optional) | -
ruby | ruby_script | list of scripts | script pointer (optional) | script name (wildcard "*" is allowed) (optional)
script | script_script | list of scripts | script pointer (optional) | script name with extension (wildcard "*" is allowed) (optional)
tcl | tcl_script | list of scripts | script pointer (optional) | script name (wildcard "*" is allowed) (optional)
weechat | bar | list of bars | bar pointer (optional) | bar name (wildcard "*" is allowed) (optional)
weechat | bar_item | list of bar items | bar item pointer (optional) | bar item name (wildcard "*" is allowed) (optional)
weechat | bar_window | list of bar windows | bar window pointer (optional) | -
weechat | buffer | list of buffers | buffer pointer (optional) | buffer name (wildcard "*" is allowed) (optional)
weechat | buffer_lines | lines of a buffer | buffer pointer | -
weechat | filter | list of filters | - | filter name (wildcard "*" is allowed) (optional)
weechat | history | history of commands | buffer pointer (if not set, return global history) (optional) | -
weechat | hook | list of hooks | hook pointer (optional) | type,arguments (type is command/timer/.., arguments to get only some hooks (wildcard "*" is allowed), both are optional)
weechat | hotlist | list of buffers in hotlist | - | -
weechat | key | list of key bindings | - | context ("default", "search", "cursor" or "mouse") (optional)
weechat | layout | list of layouts | - | -
weechat | nicklist | nicks in nicklist for a buffer | buffer pointer | nick_xxx or group_xxx to get only nick/group xxx (optional)
weechat | option | list of options | - | option name (wildcard "*" is allowed) (optional)
weechat | plugin | list of plugins | plugin pointer (optional) | plugin name (wildcard "*" is allowed) (optional)
weechat | proxy | list of proxies | proxy pointer (optional) | proxy name (wildcard "*" is allowed) (optional)
weechat | url_options | options for URL | - | -
weechat | window | list of windows | window pointer (optional) | "current" for current window or a window number (optional)
xfer | xfer | list of xfer | xfer pointer (optional) | -

C 言語での使用例:

    struct t_infolist *infolist = weechat_infolist_get ("irc_server", NULL, NULL);

スクリプト (Python) での使用例:

    # プロトタイプ
    def infolist_get(infolist_name: str, pointer: str, arguments: str) -> str: ...

    # 例
    infolist = weechat.infolist_get("irc_server", "", "")

#### infolist_next

「カーソル」をインフォリスト内の 1 つ後の要素に移動する。あるインフォリストに対するこの関数の呼び出し回数が 1 回目のの場合は、カーソルをインフォリスト内の最初の要素に移動する。

プロトタイプ:

    int weechat_infolist_next (struct t_infolist *infolist);

引数:

- infolist: インフォリストへのポインタ

戻り値:

- カーソルが 1 つ後の要素に移動した場合は 1、リストの最後に到達した場合は 0

C 言語での使用例:

    if (weechat_infolist_next (infolist))
    {
        /* read variables in item... */
    }
    else
    {
        /* no more item available */
    }

スクリプト (Python) での使用例:

    # プロトタイプ
    def infolist_next(infolist: str) -> int: ...

    # 例
    rc = weechat.infolist_next(infolist)
    if rc:
        # read variables in item...
    else:
        # no more item available

#### infolist_prev

「カーソル」をインフォリスト内の 1 つ前の要素に移動する。あるインフォリストに対するこの関数の呼び出し回数が 1 回目のの場合は、カーソルをインフォリスト内の最後の要素に移動する。

プロトタイプ:

    int weechat_infolist_prev (struct t_infolist *infolist);

引数:

- infolist: インフォリストへのポインタ

戻り値:

- カーソルが 1 つ前の要素に移動した場合は 1、リストの最初に到達した場合は 0

C 言語での使用例:

    if (weechat_infolist_prev (infolist))
    {
        /* read variables in item... */
    }
    else
    {
        /* no more item available */
    }

スクリプト (Python) での使用例:

    # プロトタイプ
    def infolist_prev(infolist: str) -> int: ...

    # 例
    rc = weechat.infolist_prev(infolist)
    if rc:
        # read variables in item...
    else:
        # no more item available

#### infolist_reset_item_cursor

インフォリストの「カーソル」をリセット。

プロトタイプ:

    void weechat_infolist_reset_item_cursor (struct t_infolist *infolist);

引数:

- infolist: インフォリストへのポインタ

C 言語での使用例:

    weechat_infolist_reset_item_cursor (infolist);

スクリプト (Python) での使用例:

    # プロトタイプ
    def infolist_reset_item_cursor(infolist: str) -> int: ...

    # 例
    weechat.infolist_reset_item_cursor(infolist)

#### infolist_search_var

WeeChat バージョン 0.4.3 以上で利用可。

現在のインフォリスト要素から変数を検索。

プロトタイプ:

    struct t_infolist_var *weechat_infolist_search_var (struct t_infolist *infolist,
                                                        const char *name);

引数:

- infolist: インフォリストへのポインタ

- name: 変数名

戻り値:

- 見つかった変数へのポインタ、見つからない場合は NULL

C 言語での使用例:

    if (weechat_infolist_search_var (infolist, "name"))
    {
        /* 変数 "name" が存在する場合 */
        /* ... */
    }

スクリプト (Python) での使用例:

    # プロトタイプ
    def infolist_search_var(infolist: str, name: str) -> str: ...

    # 例
    if weechat.infolist_search_var(infolist, "name"):
        # 変数 "name" が存在する場合
        # ...

#### infolist_fields

現在のインフォリストの要素に対するフィールドのリストを返す。

プロトタイプ:

    const char *weechat_infolist_fields (struct t_infolist *infolist);

引数:

- infolist: インフォリストへのポインタ

戻り値:

- 指定したインフォリストの要素に含まれる変数名のリスト。以下の変数名に対応する型の文字を含むコンマ区切りリスト、型は: "i" (整数)、"s" (文字列)、"p" (ポインタ)、"b" (バッファ)、"t" (時刻)。

C 言語での使用例:

    const char *fields = weechat_infolist_fields (infolist);
    /* fields contains something like:
       "i:my_integer,s:my_string,p:my_pointer,b:my_buffer,t:my_time" */

スクリプト (Python) での使用例:

    # プロトタイプ
    def infolist_fields(infolist: str) -> str: ...

    # 例
    fields = weechat.infolist_fields(infolist)
    # fields contains something like:
    # "i:my_integer,s:my_string,p:my_pointer,b:my_buffer,t:my_time"

#### infolist_integer

現在のインフォリストの要素に含まれる整数変数の値を返す。

プロトタイプ:

    int weechat_infolist_integer (struct t_infolist *infolist, const char *var);

引数:

- infolist: インフォリストへのポインタ

- var: 変数名 (必ず「整数」型)

戻り値:

- 変数の整数値

C 言語での使用例:

    weechat_printf (NULL, "integer = %d",
                    weechat_infolist_integer (infolist, "my_integer"));

スクリプト (Python) での使用例:

    # プロトタイプ
    def infolist_integer(infolist: str, var: str) -> int: ...

    # 例
    weechat.prnt("", "integer = %d" % weechat.infolist_integer(infolist, "my_integer"))

#### infolist_string

現在のインフォリストの要素に含まれる文字列変数の値を返す。

プロトタイプ:

    const char *weechat_infolist_string (struct t_infolist *infolist, const char *var);

引数:

- infolist: インフォリストへのポインタ

- var: 変数名 (必ず「文字列」型)

戻り値:

- 変数の文字列値

C 言語での使用例:

    weechat_printf (NULL, "string = %s",
                    weechat_infolist_string (infolist, "my_string"));

スクリプト (Python) での使用例:

    # プロトタイプ
    def infolist_string(infolist: str, var: str) -> str: ...

    # 例
    weechat.prnt("", "string = %s" % weechat.infolist_string(infolist, "my_string"))

#### infolist_pointer

現在のインフォリストの要素に含まれるポインタ変数の値を返す。

プロトタイプ:

    void *weechat_infolist_pointer (struct t_infolist *infolist, const char *var);

引数:

- infolist: インフォリストへのポインタ

- var: 変数名 (必ず「ポインタ」型)

戻り値:

- 変数のポインタ値

C 言語での使用例:

    weechat_printf (NULL, "pointer = %p", weechat_infolist_pointer (infolist, "my_pointer"));

スクリプト (Python) での使用例:

    # プロトタイプ
    def infolist_pointer(infolist: str, var: str) -> str: ...

    # 例
    weechat.prnt("", "pointer = 0x%s" % weechat.infolist_pointer(infolist, "my_pointer"))

#### infolist_buffer

現在のインフォリストの要素に含まれるバッファ変数の値を返す。

プロトタイプ:

    void *weechat_infolist_buffer (struct t_infolist *infolist, const char *var,
                                   int *size);

引数:

- infolist: インフォリストへのポインタ

- var: 変数名 (必ず「バッファ」型)

- size: 整数変数へのポインタ、バッファサイズを返す

戻り値:

- バッファへのポインタ

C 言語での使用例:

    int size;
    void *pointer = weechat_infolist_buffer (infolist, "my_buffer", &size);
    weechat_printf (NULL, "buffer = %p, size = %d", pointer, size);

注記 | スクリプト API ではこの関数を利用できません。

#### infolist_time

現在のインフォリストの要素に含まれる時刻変数の値を返す。

プロトタイプ:

    time_t weechat_infolist_time (struct t_infolist *infolist, const char *var);

引数:

- infolist: インフォリストへのポインタ

- var: 変数名 (必ず「時刻」型)

戻り値:

- 変数の時刻値

C 言語での使用例:

    weechat_printf (NULL, "time = %ld",
                    weechat_infolist_time (infolist, "my_time"));

スクリプト (Python) での使用例:

    # プロトタイプ
    def infolist_time(infolist: str, var: str) -> int: ...

    # 例
    weechat.prnt("", "time = %d" % weechat.infolist_time(infolist, "my_time"))

#### infolist_free

インフォリストの領域を開放。

プロトタイプ:

    void weechat_infolist_free (struct t_infolist *infolist);

引数:

- infolist: インフォリストへのポインタ

C 言語での使用例:

    weechat_infolist_free (infolist);

スクリプト (Python) での使用例:

    # プロトタイプ
    def infolist_free(infolist: str) -> int: ...

    # 例
    weechat.infolist_free(infolist)

### 3.25. Hdata

hdata に対する関数 (WeeChat またはプラグインデータへの直アクセス)。

重要 | hdata を使うことで読み取り専用でデータにアクセスできます。hdata 変数が示すメモリ領域に何かを書き込むことは 厳禁 です。 データを更新する場合は必ず関数 hdata_update を使ってください。

#### hdata_new

WeeChat バージョン 0.3.6 以上で利用可、バージョン 0.3.9 と 0.4.0 で更新。

新規の hdata を作成。

注記

hdata vs インフォリスト

Hdata を使うことで高速に WeeChat およびプラグインのデータを読み出す事ができます。hdata はインフォリストと似ていますが、異なる点もあります:

- hdata はインフォリストに比べて高速でメモリを節約できる: データを複製せずに直接読み出す。

- hdata とインフォリストのデータは異なる場合がある: hdata 構造体には生データ以外は含まれない (利便性を考慮してインフォリストには余分なデータが追加されている)

プロトタイプ:

    struct t_hdata *weechat_hdata_new (const char *hdata_name, const char *var_prev, const char *var_next,
                                       int create_allowed, int delete_allowed,
                                       int (*callback_update)(void *data,
                                                              struct t_hdata *hdata,
                                                              void *pointer,
                                                              struct t_hashtable *hashtable),
                                       void *callback_update_data);

引数:

- hdata_name: hdata の名前

- var_prev: 構造体に含まれる変数名。構造体は配列の 1 つ前の要素へのポインタ (変数が利用不可能な場合は NULL でも可)

- var_next: 構造体に含まれる変数名。構造体は配列の 1 つ後の要素へのポインタ (変数が利用不可能な場合は NULL でも可)

- create_allowed: 構造体の作成を許可する場合は 1、それ以外の場合は 0 (WeeChat バージョン 0.4.0 以上で利用可)

- delete_allowed: 構造体の削除を許可する場合は 1、それ以外の場合は 0 (WeeChat バージョン 0.3.9 以上で利用可)

- callback_update: hdata 内のデータを更新する際のコールバック関数、データの更新を禁止する場合は NULL (WeeChat バージョン 0.3.9 以上で利用可)、引数と戻り値:

  - void *data: ポインタ

  - struct t_hdata *hdata: hdata へのポインタ

  - struct t_hashtable *hashtable: 更新する変数を含むハッシュテーブル (hdata_update を参照)

  - return value: 更新された変数の数

- callback_update_data: WeeChat が callback_update コールバックを呼び出す際にコールバックに渡すポインタ (WeeChat バージョン 0.3.9 以上で利用可)

戻り値:

- 新しい hdata へのポインタ

C 言語での使用例:

    struct t_hdata *hdata = weechat_hdata_new ("myplugin_list", "prev", "next", 0, 0, &callback_update, NULL);

注記 | スクリプト API ではこの関数を利用できません。

#### hdata_new_var

WeeChat ≥ 0.3.6, updated in 0.3.7, 0.3.9, 0.4.3, 3.4, 4.3.0.

hdata に新しい変数を作成。

プロトタイプ:

    void weechat_hdata_new_var (struct t_hdata *hdata, const char *name, int offset, int type,
                                int update_allowed, const char *array_size, const char *hdata_name);

引数:

- hdata: hdata へのポインタ

- name: 変数名

- offset: 構造体における変数のオフセット

- type: 変数型、以下の 1 つ:

  - WEECHAT_HDATA_CHAR

  - WEECHAT_HDATA_INTEGER

  - WEECHAT_HDATA_LONG

  - WEECHAT_HDATA_LONGLONG (WeeChat ≥ 4.3.0)

  - WEECHAT_HDATA_STRING

  - WEECHAT_HDATA_SHARED_STRING (WeeChat ≥ 0.4.3)

  - WEECHAT_HDATA_POINTER

  - WEECHAT_HDATA_TIME

  - WEECHAT_HDATA_HASHTABLE (WeeChat ≥ 0.3.7)

  - WEECHAT_HDATA_OTHER

- update_allowed: 変数の更新を許可する場合は 1、禁止する場合は 0 (WeeChat バージョン 0.3.9 以上で利用可)

- array_size: 配列でない場合は必ず NULL、配列の場合の値は: (WeeChat バージョン 0.3.9 以上で利用可)

  - hdata に含まれる変数の名前: 配列のサイズはこの名前の変数に収められている (配列サイズは動的に変化)

  - 整数 (文字列): 配列のサイズは固定

  - *: 自動サイズ: 配列のサイズは値の中に見つかる最初の NULL を元に計算されます (文字列、ポインタ、ハッシュテーブル型以外では使えません)

- hdata_name: hdata の名前 (変数が hdata を含む構造体へのポインタの場合)

With WeeChat ≥ 3.4, the array_size parameter can be prefixed with `*,` for pointer to dynamically allocated array (without this prefix, the array is considered static).

Examples of variables and the corresponding array size (WeeChat ≥ 3.4):

Variable declaration in C | Hdata type | Array size | Description
--- | --- | --- | ---
`int *numbers;` | `WEECHAT_HDATA_INTEGER` | `*,2` | Allocated array of 2 integers.
`int *numbers;` | `WEECHAT_HDATA_INTEGER` | `*,array_size` | Allocated array of integers, the size is stored in another variable called "array_size".
`int numbers[3];` | `WEECHAT_HDATA_INTEGER` | `3` | Static array of 3 integers.
`char **words;` | `WEECHAT_HDATA_STRING` | `*,*` | Allocated array of strings, dynamic size (NULL pointer must be present after last word).
`char **words;` | `WEECHAT_HDATA_STRING` | `*,count_words` | Allocated array of strings, the size is stored in another variable called "count_words".

C 言語での使用例:

    struct t_myplugin_list
    {
        char *name;
        struct t_gui_buffer *buffer;
        int numbers[3];
        int tags_count;
        char **tags_array;
        char **string_split;
        struct t_myplugin_list *prev;
        struct t_myplugin_list *next;
    };

    /* ... */

    struct t_hdata *hdata = weechat_hdata_new ("myplugin_list", "prev", "next");
    weechat_hdata_new_var (hdata, "name", offsetof (struct t_myplugin_list, name), WEECHAT_HDATA_STRING, 0, NULL, NULL);
    weechat_hdata_new_var (hdata, "buffer", offsetof (struct t_myplugin_list, buffer), WEECHAT_HDATA_POINTER, 0, NULL, NULL);
    weechat_hdata_new_var (hdata, "numbers", offsetof (struct t_myplugin_list, numbers), WEECHAT_HDATA_INTEGER, 0, "3", NULL);
    weechat_hdata_new_var (hdata, "tags_count", offsetof (struct t_myplugin_list, tags_count), WEECHAT_HDATA_INTEGER, 0, NULL, NULL);
    weechat_hdata_new_var (hdata, "tags_array", offsetof (struct t_myplugin_list, tags_array), WEECHAT_HDATA_STRING, 0, "*,tags_count", NULL);
    weechat_hdata_new_var (hdata, "string_split", offsetof (struct t_myplugin_list, string_split), WEECHAT_HDATA_STRING, 0, "*,*", NULL);
    weechat_hdata_new_var (hdata, "prev", offsetof (struct t_myplugin_list, prev), WEECHAT_HDATA_POINTER, 0, NULL, "myplugin_list");
    weechat_hdata_new_var (hdata, "next", offsetof (struct t_myplugin_list, next), WEECHAT_HDATA_POINTER, 0, NULL, "myplugin_list");

コードを短くするためにはマクロ "WEECHAT_HDATA_VAR" を使います。

    WEECHAT_HDATA_VAR(struct t_myplugin_list, name, STRING, 0, NULL, NULL);
    WEECHAT_HDATA_VAR(struct t_myplugin_list, buffer, POINTER, 0, NULL, NULL);
    WEECHAT_HDATA_VAR(struct t_myplugin_list, numbers, INTEGER, 0, "3", NULL);
    WEECHAT_HDATA_VAR(struct t_myplugin_list, tags_count, INTEGER, 0, NULL, NULL);
    WEECHAT_HDATA_VAR(struct t_myplugin_list, tags_array, STRING, 0, "*,tags_count", NULL);
    WEECHAT_HDATA_VAR(struct t_myplugin_list, string_split, STRING, 0, "*,*", NULL);
    WEECHAT_HDATA_VAR(struct t_myplugin_list, prev, POINTER, 0, NULL, "myplugin_list");
    WEECHAT_HDATA_VAR(struct t_myplugin_list, next, POINTER, 0, NULL, "myplugin_list");

注記 | スクリプト API ではこの関数を利用できません。

#### hdata_new_list

WeeChat バージョン 0.3.6 以上で利用可、バージョン 1.0 で更新。

hdata に新しいリストへのポインタを作成。

プロトタイプ:

    void weechat_hdata_new_list (struct t_hdata *hdata, const char *name, void *pointer, int flags);

引数:

- hdata: hdata へのポインタ

- name: 変数名

- pointer: リストへのポインタ

- flags: 以下の値の組み合わせ: (WeeChat バージョン 1.0 以上)

  - WEECHAT_HDATA_LIST_CHECK_POINTERS: ポインタをチェックする際に使うリスト

C 言語での使用例:

    struct t_myplugin_list
    {
        char *name;
        struct t_gui_buffer *buffer;
        int tags_count;
        char **tags_array;
        char **string_split;
        struct t_myplugin_list *prev;
        struct t_myplugin_list *next;
    };

    /* ... */

    struct t_hdata *hdata = weechat_hdata_new ("myplugin_list", "prev", "next");
    weechat_hdata_new_var (hdata, "name", offsetof (struct t_myplugin_list, name), WEECHAT_HDATA_STRING, NULL, NULL);
    weechat_hdata_new_var (hdata, "buffer", offsetof (struct t_myplugin_list, buffer), WEECHAT_HDATA_POINTER, NULL, NULL);
    weechat_hdata_new_var (hdata, "tags_count", offsetof (struct t_myplugin_list, tags_count), WEECHAT_HDATA_INTEGER, NULL, NULL);
    weechat_hdata_new_var (hdata, "tags_array", offsetof (struct t_myplugin_list, tags_array), WEECHAT_HDATA_STRING, "tags_count", NULL);
    weechat_hdata_new_var (hdata, "string_split", offsetof (struct t_myplugin_list, string_split), WEECHAT_HDATA_STRING, "*", NULL);
    weechat_hdata_new_var (hdata, "prev", offsetof (struct t_myplugin_list, prev), WEECHAT_HDATA_POINTER, NULL, "myplugin_list");
    weechat_hdata_new_var (hdata, "next", offsetof (struct t_myplugin_list, next), WEECHAT_HDATA_POINTER, NULL, "myplugin_list");

    weechat_hdata_new_list (hdata, "buffers", &buffers, WEECHAT_HDATA_LIST_CHECK_POINTERS);
    weechat_hdata_new_list (hdata, "last_buffer", &last_buffer, 0);

コードを短くするためにはマクロ "WEECHAT_HDATA_LIST" を使います。

    WEECHAT_HDATA_LIST(buffers, WEECHAT_HDATA_LIST_CHECK_POINTERS);
    WEECHAT_HDATA_LIST(last_buffer, 0);

注記 | スクリプト API ではこの関数を利用できません。

#### hdata_get

WeeChat バージョン 0.3.6 以上で利用可。

WeeChat およびプラグイン構造体に対する hdata を返す。

注記 | hdata はデータを含みません、hdata は構造体における変数の位置を含むただのハッシュテーブル。つまりデータを読み出すためには hdata と WeeChat およびプラグインへのポインタが必要です。

プロトタイプ:

    struct t_hdata *weechat_hdata_get (const char *hdata_name);

引数:

- hdata_name: hdata の名前

戻り値:

- hdata へのポインタ、エラーが起きた場合は NULL

hdata のリスト:

Plugin | Name | Description | Lists | Variables
--- | --- | --- | --- | ---
fset | fset_option | fset options | - | index (integer) file (string) section (string) option (string) name (string) parent_name (string) type (integer) default_value (string) value (string) parent_value (string) min (string) max (string) description (string) string_values (string) marked (integer)
guile | guile_script | list of scripts | scripts last_script | filename (string) interpreter (pointer) name (string) author (string) version (string) license (string) description (string) shutdown_func (string) charset (string) unloading (integer) prev_script (pointer, hdata: "guile_script") next_script (pointer, hdata: "guile_script")
irc | irc_batch | irc batch | - | reference (string) parent_ref (string) type (string) parameters (string) start_time (time) messages (pointer) end_received (integer) messages_processed (integer) prev_batch (pointer, hdata: "irc_batch") next_batch (pointer, hdata: "irc_batch")

irc

irc_channel

irc channel

-

type (integer)
name (string)
topic (string)
modes (string)
limit (integer)
key (string)
join_msg_received (hashtable)
checking_whox (integer)
away_message (string)
has_quit_server (integer)
cycle (integer)
part (integer)
nick_completion_reset (integer)
pv_remote_nick_color (string)
hook_autorejoin (pointer)
nicks_count (integer)
nicks (pointer, hdata: "irc_nick")
last_nick (pointer, hdata: "irc_nick")
nicks_speaking (pointer)
nicks_speaking_time (pointer, hdata: "irc_channel_speaking")
last_nick_speaking_time (pointer, hdata: "irc_channel_speaking")
modelists (pointer, hdata: "irc_modelist")
last_modelist (pointer, hdata: "irc_modelist")
join_smart_filtered (hashtable)
typing_state (integer)
typing_status_sent (time)
buffer (pointer, hdata: "buffer")
buffer_as_string (string)
prev_channel (pointer, hdata: "irc_channel")
next_channel (pointer, hdata: "irc_channel")

irc | irc_channel_speaking | irc channel_speaking | - | nick (string) time_last_message (time) prev_nick (pointer, hdata: "irc_channel_speaking") next_nick (pointer, hdata: "irc_channel_speaking")
irc | irc_ignore | irc ignore | irc_ignore_list last_irc_ignore | number (integer) mask (string) regex_mask (pointer) server (string) channel (string) prev_ignore (pointer, hdata: "irc_ignore") next_ignore (pointer, hdata: "irc_ignore")
irc | irc_list | irc data for /list buffer | - | buffer (pointer, hdata: "buffer") channels (pointer) filter_channels (pointer) name_max_length (integer) filter (string) sort (string) sort_fields (pointer) sort_fields_count (integer) selected_line (integer)
irc | irc_list_channel | irc channel on /list buffer | - | name (string) name2 (string) users (integer) topic (string)
irc | irc_modelist | irc modelist | - | type (char) state (integer) items (pointer, hdata: "irc_modelist_item") last_item (pointer, hdata: "irc_modelist_item") prev_modelist (pointer, hdata: "irc_modelist") next_modelist (pointer, hdata: "irc_modelist")
irc | irc_modelist_item | irc modelist item | - | number (integer) mask (string) setter (string) datetime (time) prev_item (pointer, hdata: "irc_modelist_item") next_item (pointer, hdata: "irc_modelist_item")
irc | irc_nick | irc nick | - | name (string) host (string) prefixes (string) prefix (string) away (integer) account (string) realname (string) color (string) prev_nick (pointer, hdata: "irc_nick") next_nick (pointer, hdata: "irc_nick")
irc | irc_notify | irc notify | - | server (pointer, hdata: "irc_server") nick (string) check_away (integer) is_on_server (integer) away_message (string) ison_received (integer) prev_notify (pointer, hdata: "irc_notify") next_notify (pointer, hdata: "irc_notify")

irc

irc_redirect

irc redirect

-

server (pointer, hdata: "irc_server")
pattern (string)
signal (string)
count (integer)
current_count (integer)
string (string)
timeout (integer)
command (string)
assigned_to_command (integer)
start_time (time)
cmd_start (hashtable)
cmd_stop (hashtable)
cmd_extra (hashtable)
cmd_start_received (integer)
cmd_stop_received (integer)
cmd_filter (hashtable)
output (string)
output_size (integer)
prev_redirect (pointer, hdata: "irc_redirect")
next_redirect (pointer, hdata: "irc_redirect")

irc | irc_redirect_pattern | pattern for irc redirect | irc_redirect_patterns last_irc_redirect_pattern | name (string) temp_pattern (integer) timeout (integer) cmd_start (string) cmd_stop (string) cmd_extra (string) prev_redirect (pointer, hdata: "irc_redirect_pattern") next_redirect (pointer, hdata: "irc_redirect_pattern")

irc

irc_server

irc server

irc_servers
last_irc_server

name (string)
options (pointer)
fake_server (integer)
reloading_from_config (integer)
reloaded_from_config (integer)
addresses_eval (string)
addresses_count (integer)
addresses_array (string, array_size: "addresses_count")
ports_array (integer, array_size: "addresses_count")
retry_array (integer, array_size: "addresses_count")
index_current_address (integer)
current_address (string)
current_ip (string)
current_port (integer)
current_retry (integer)
sock (integer)
hook_connect (pointer, hdata: "hook")
hook_fd (pointer, hdata: "hook")
hook_timer_connection (pointer, hdata: "hook")
hook_timer_sasl (pointer, hdata: "hook")
hook_timer_anti_flood (pointer, hdata: "hook")
sasl_scram_client_first (string)
sasl_scram_salted_pwd (other)
sasl_scram_salted_pwd_size (integer)
sasl_scram_auth_message (string)
sasl_temp_username (string)
sasl_temp_password (string)
authentication_method (integer)
sasl_mechanism_used (integer)
is_connected (integer)
tls_connected (integer)
disconnected (integer)
gnutls_sess (pointer)
tls_cert (pointer)
tls_cert_key (pointer)
unterminated_message (string)
nicks_count (integer)
nicks_array (string, array_size: "nicks_count")
nick_first_tried (integer)
nick_alternate_number (integer)
nick (string)
nick_modes (string)
host (string)
checking_cap_ls (integer)
cap_ls (hashtable)
checking_cap_list (integer)
cap_list (hashtable)
multiline_max_bytes (integer)
multiline_max_lines (integer)
isupport (string)
prefix_modes (string)
prefix_chars (string)
msg_max_length (integer)
user_max_length (integer)
host_max_length (integer)
casemapping (integer)
utf8mapping (integer)
utf8only (integer)
chantypes (string)
chanmodes (string)
monitor (integer)
monitor_time (time)
clienttagdeny (string)
clienttagdeny_count (integer)
clienttagdeny_array (string, array_size: "clienttagdeny_count")
typing_allowed (integer)
reconnect_delay (integer)
reconnect_start (time)
command_time (time)
autojoin_time (time)
autojoin_done (integer)
disable_autojoin (integer)
is_away (integer)
away_message (string)
away_time (time)
lag (integer)
lag_displayed (integer)
lag_check_time (other)
lag_next_check (time)
lag_last_refresh (time)
cmd_list_regexp (pointer)
list (pointer, hdata: "irc_list")
last_away_check (time)
last_data_purge (time)
outqueue (pointer)
last_outqueue (pointer)
redirects (pointer, hdata: "irc_redirect")
last_redirect (pointer, hdata: "irc_redirect")
notify_list (pointer, hdata: "irc_notify")
last_notify (pointer, hdata: "irc_notify")
notify_count (integer)
join_manual (hashtable)
join_channel_key (hashtable)
join_noswitch (hashtable)
echo_msg_recv (hashtable)
names_channel_filter (hashtable)
batches (pointer, hdata: "irc_batch")
last_batch (pointer, hdata: "irc_batch")
buffer (pointer, hdata: "buffer")
buffer_as_string (string)
channels (pointer, hdata: "irc_channel")
last_channel (pointer, hdata: "irc_channel")
prev_server (pointer, hdata: "irc_server")
next_server (pointer, hdata: "irc_server")

lua | lua_script | list of scripts | scripts last_script | filename (string) interpreter (pointer) name (string) author (string) version (string) license (string) description (string) shutdown_func (string) charset (string) unloading (integer) prev_script (pointer, hdata: "lua_script") next_script (pointer, hdata: "lua_script")
perl | perl_script | list of scripts | scripts last_script | filename (string) interpreter (pointer) name (string) author (string) version (string) license (string) description (string) shutdown_func (string) charset (string) unloading (integer) prev_script (pointer, hdata: "perl_script") next_script (pointer, hdata: "perl_script")
php | php_script | list of scripts | scripts last_script | filename (string) interpreter (pointer) name (string) author (string) version (string) license (string) description (string) shutdown_func (string) charset (string) unloading (integer) prev_script (pointer, hdata: "php_script") next_script (pointer, hdata: "php_script")
python | python_script | list of scripts | scripts last_script | filename (string) interpreter (pointer) name (string) author (string) version (string) license (string) description (string) shutdown_func (string) charset (string) unloading (integer) prev_script (pointer, hdata: "python_script") next_script (pointer, hdata: "python_script")
ruby | ruby_script | list of scripts | scripts last_script | filename (string) interpreter (pointer) name (string) author (string) version (string) license (string) description (string) shutdown_func (string) charset (string) unloading (integer) prev_script (pointer, hdata: "ruby_script") next_script (pointer, hdata: "ruby_script")

script

script_script

scripts from repository

scripts_repo
last_script_repo

name (string)
name_with_extension (string)
language (integer)
author (string)
mail (string)
version (string)
license (string)
description (string)
tags (string)
requirements (string)
min_weechat (string)
max_weechat (string)
sha512sum (string)
url (string)
popularity (integer)
date_added (time)
date_updated (time)
status (integer)
version_loaded (string)
displayed (integer)
install_order (integer)
prev_script (pointer, hdata: "script_script")
next_script (pointer, hdata: "script_script")

tcl | tcl_script | list of scripts | scripts last_script | filename (string) interpreter (pointer) name (string) author (string) version (string) license (string) description (string) shutdown_func (string) charset (string) unloading (integer) prev_script (pointer, hdata: "tcl_script") next_script (pointer, hdata: "tcl_script")
weechat | bar | bar | gui_bars last_gui_bar | name (string) options (pointer) items_count (integer) items_subcount (pointer) items_array (pointer) items_buffer (pointer) items_prefix (pointer) items_name (pointer) items_suffix (pointer) bar_window (pointer, hdata: "bar_window") bar_refresh_needed (integer) prev_bar (pointer, hdata: "bar") next_bar (pointer, hdata: "bar")
weechat | bar_item | bar item | gui_bar_items last_gui_bar_item | plugin (pointer, hdata: "plugin") name (string) build_callback (pointer) build_callback_pointer (pointer) build_callback_data (pointer) prev_item (pointer, hdata: "bar_item") next_item (pointer, hdata: "bar_item")

weechat

bar_window

bar window

-

bar (pointer, hdata: "bar")
x (integer)
y (integer)
width (integer)
height (integer)
scroll_x (integer)
scroll_y (integer)
cursor_x (integer)
cursor_y (integer)
current_size (integer)
items_count (integer)
items_subcount (pointer)
items_content (pointer)
items_num_lines (pointer)
items_refresh_needed (pointer)
screen_col_size (integer)
screen_lines (integer)
coords_count (integer)
coords (pointer)
gui_objects (pointer)
prev_bar_window (pointer, hdata: "bar_window")
next_bar_window (pointer, hdata: "bar_window")

Update allowed:
scroll_x (integer)
scroll_y (integer)

weechat

buffer

buffer

gui_buffer_last_displayed
gui_buffers
last_gui_buffer

id (longlong)
opening (integer)
plugin (pointer, hdata: "plugin")
plugin_name_for_upgrade (string)
number (integer)
old_number (integer)
layout_number (integer)
layout_number_merge_order (integer)
name (string)
full_name (string)
old_full_name (string)
short_name (string)
type (integer)
notify (integer)
num_displayed (integer)
active (integer)
hidden (integer)
zoomed (integer)
print_hooks_enabled (integer)
day_change (integer)
clear (integer)
filter (integer)
close_callback (pointer)
close_callback_pointer (pointer)
close_callback_data (pointer)
closing (integer)
title (string)
modes (string)
own_lines (pointer, hdata: "lines")
mixed_lines (pointer, hdata: "lines")
lines (pointer, hdata: "lines")
next_line_id (integer)
time_for_each_line (integer)
chat_refresh_needed (integer)
nicklist (integer)
nicklist_case_sensitive (integer)
nicklist_root (pointer, hdata: "nick_group")
nicklist_max_length (integer)
nicklist_display_groups (integer)
nicklist_count (integer)
nicklist_visible_count (integer)
nicklist_groups_count (integer)
nicklist_groups_visible_count (integer)
nicklist_nicks_count (integer)
nicklist_nicks_visible_count (integer)
nicklist_last_id_assigned (longlong)
nickcmp_callback (pointer)
nickcmp_callback_pointer (pointer)
nickcmp_callback_data (pointer)
input (integer)
input_callback (pointer)
input_callback_pointer (pointer)
input_callback_data (pointer)
input_get_any_user_data (integer)
input_get_unknown_commands (integer)
input_get_empty (integer)
input_multiline (integer)
input_prompt (string)
input_buffer (string)
input_buffer_alloc (integer)
input_buffer_size (integer)
input_buffer_length (integer)
input_buffer_pos (integer)
input_buffer_1st_display (integer)
input_undo_snap (pointer, hdata: "input_undo")
input_undo (pointer, hdata: "input_undo")
last_input_undo (pointer, hdata: "input_undo")
ptr_input_undo (pointer, hdata: "input_undo")
input_undo_count (integer)
completion (pointer, hdata: "completion")
history (pointer, hdata: "history")
last_history (pointer, hdata: "history")
ptr_history (pointer, hdata: "history")
num_history (integer)
text_search (integer)
text_search_direction (integer)
text_search_exact (integer)
text_search_regex (integer)
text_search_regex_compiled (pointer)
text_search_where (integer)
text_search_history (integer)
text_search_found (integer)
text_search_ptr_history (pointer, hdata: "history")
text_search_input (string)
highlight_words (string)
highlight_regex (string)
highlight_regex_compiled (pointer)
highlight_disable_regex (string)
highlight_disable_regex_compiled (pointer)
highlight_tags_restrict (string)
highlight_tags_restrict_count (integer)
highlight_tags_restrict_array (pointer, array_size: "highlight_tags_restrict_count")
highlight_tags (string)
highlight_tags_count (integer)
highlight_tags_array (pointer, array_size: "highlight_tags_count")
hotlist (pointer, hdata: "hotlist")
hotlist_max_level_nicks (hashtable)
keys (pointer, hdata: "key")
last_key (pointer, hdata: "key")
keys_count (integer)
local_variables (hashtable)
prev_buffer (pointer, hdata: "buffer")
next_buffer (pointer, hdata: "buffer")

weechat | buffer_visited | visited buffer | gui_buffers_visited last_gui_buffer_visited | buffer (pointer, hdata: "buffer") prev_buffer (pointer, hdata: "buffer_visited") next_buffer (pointer, hdata: "buffer_visited")

weechat

completion

structure with completion

weechat_completions
last_weechat_completion

plugin (pointer, hdata: "plugin")
buffer (pointer, hdata: "buffer")
context (integer)
case_sensitive (integer)
base_command (string)
base_command_arg_index (integer)
base_word (string)
base_word_pos (integer)
position (integer)
args (string)
direction (integer)
add_space (integer)
partial_completion (integer)
template_partial_completion (integer)
list (pointer)
word_found (string)
word_found_is_nick (integer)
position_replace (integer)
diff_size (integer)
diff_length (integer)
partial_list (pointer)
prev_completion (pointer, hdata: "completion")
next_completion (pointer, hdata: "completion")

weechat | completion_word | structure with word found for a completion | - | word (string) nick_completion (char) count (integer)

weechat

config_file

config file

config_files
last_config_file

plugin (pointer, hdata: "plugin")
priority (integer)
name (string)
filename (string)
file (pointer)
version (integer)
callback_reload (pointer)
callback_reload_pointer (pointer)
callback_reload_data (pointer)
sections (pointer, hdata: "config_section")
last_section (pointer, hdata: "config_section")
prev_config (pointer, hdata: "config_file")
next_config (pointer, hdata: "config_file")

weechat

config_option

config option

-

config_file (pointer, hdata: "config_file")
section (pointer, hdata: "config_section")
name (string)
parent_name (string)
type (integer)
description (string)
string_values (string, array_size: "*")
min (integer)
max (integer)
default_value (pointer)
value (pointer)
null_value_allowed (integer)
callback_check_value (pointer)
callback_check_value_pointer (pointer)
callback_check_value_data (pointer)
callback_change (pointer)
callback_change_pointer (pointer)
callback_change_data (pointer)
callback_delete (pointer)
callback_delete_pointer (pointer)
callback_delete_data (pointer)
loaded (integer)
prev_option (pointer, hdata: "config_option")
next_option (pointer, hdata: "config_option")

weechat

config_section

config section

-

config_file (pointer, hdata: "config_file")
name (string)
user_can_add_options (integer)
user_can_delete_options (integer)
callback_read (pointer)
callback_read_pointer (pointer)
callback_read_data (pointer)
callback_write (pointer)
callback_write_pointer (pointer)
callback_write_data (pointer)
callback_write_default (pointer)
callback_write_default_pointer (pointer)
callback_write_default_data (pointer)
callback_create_option (pointer)
callback_create_option_pointer (pointer)
callback_create_option_data (pointer)
callback_delete_option (pointer)
callback_delete_option_pointer (pointer)
callback_delete_option_data (pointer)
options (pointer, hdata: "config_option")
last_option (pointer, hdata: "config_option")
prev_section (pointer, hdata: "config_section")
next_section (pointer, hdata: "config_section")

weechat | filter | filter | gui_filters last_gui_filter | enabled (integer) name (string) buffer_name (string) num_buffers (integer) buffers (pointer) tags (string) tags_count (integer) tags_array (pointer, array_size: "tags_count") regex (string) regex_prefix (pointer) regex_message (pointer) prev_filter (pointer, hdata: "filter") next_filter (pointer, hdata: "filter")
weechat | history | history of commands in buffer | gui_history last_gui_history | text (string) next_history (pointer, hdata: "history") prev_history (pointer, hdata: "history") Update allowed: __create __delete

weechat

hook

hook

weechat_hooks_command
weechat_hooks_command_run
weechat_hooks_completion
weechat_hooks_config
weechat_hooks_connect
weechat_hooks_fd
weechat_hooks_focus
weechat_hooks_hdata
weechat_hooks_hsignal
weechat_hooks_info
weechat_hooks_info_hashtable
weechat_hooks_infolist
weechat_hooks_line
weechat_hooks_modifier
weechat_hooks_print
weechat_hooks_process
weechat_hooks_signal
weechat_hooks_timer
weechat_hooks_url
last_weechat_hook_command
last_weechat_hook_command_run
last_weechat_hook_completion
last_weechat_hook_config
last_weechat_hook_connect
last_weechat_hook_fd
last_weechat_hook_focus
last_weechat_hook_hdata
last_weechat_hook_hsignal
last_weechat_hook_info
last_weechat_hook_info_hashtable
last_weechat_hook_infolist
last_weechat_hook_line
last_weechat_hook_modifier
last_weechat_hook_print
last_weechat_hook_process
last_weechat_hook_signal
last_weechat_hook_timer
last_weechat_hook_url

plugin (pointer, hdata: "plugin")
subplugin (string)
type (integer)
deleted (integer)
running (integer)
priority (integer)
callback_pointer (pointer)
callback_data (pointer)
hook_data (pointer)
prev_hook (pointer, hdata: "hook")
next_hook (pointer, hdata: "hook")

weechat

hook_command

hook "command"

-

callback (pointer)
command (string)
description (string)
args (string)
args_description (string)
completion (string)
cplt_num_templates (integer)
cplt_templates (pointer, array_size: "cplt_num_templates")
cplt_templates_static (pointer, array_size: "cplt_num_templates")
cplt_template_num_args (integer, array_size: "cplt_num_templates")
cplt_template_args (pointer, array_size: "cplt_num_templates")
cplt_template_num_args_concat (integer)
cplt_template_args_concat (pointer, array_size: "cplt_template_num_args_concat")
keep_spaces_right (integer)

weechat | hook_command_run | hook "command_run" | - | callback (pointer) command (string) keep_spaces_right (integer)
weechat | hook_completion | hook "completion" | - | callback (pointer) completion_item (string) description (string)
weechat | hook_config | hook "config" | - | callback (pointer) option (string)

weechat

hook_connect

hook "connect"

-

callback (pointer)
proxy (string)
address (string)
port (integer)
ipv6 (integer)
sock (integer)
retry (integer)
gnutls_sess (pointer)
gnutls_cb (pointer)
gnutls_dhkey_size (integer)
gnutls_priorities (string)
local_hostname (string)
child_read (integer)
child_write (integer)
child_recv (integer)
child_send (integer)
child_pid (integer)
hook_child_timer (pointer, hdata: "hook")
hook_fd (pointer, hdata: "hook")
handshake_hook_fd (pointer, hdata: "hook")
handshake_hook_timer (pointer, hdata: "hook")
handshake_fd_flags (integer)
handshake_ip_address (string)
sock_v4 (integer, array_size: "4")
sock_v6 (integer, array_size: "4")

weechat | hook_fd | hook "fd" | - | callback (pointer) fd (integer) flags (integer) error (integer)
weechat | hook_focus | hook "focus" | - | callback (pointer) area (string)
weechat | hook_hdata | hook "hdata" | - | callback (pointer) hdata_name (string) description (string)
weechat | hook_hsignal | hook "hsignal" | - | callback (pointer) signals (string, array_size: "num_signals") num_signals (integer)
weechat | hook_info | hook "info" | - | callback (pointer) info_name (string) description (string) args_description (string)
weechat | hook_info_hashtable | hook "info_hashtable" | - | callback (pointer) info_name (string) description (string) args_description (string) output_description (string)
weechat | hook_infolist | hook "infolist" | - | callback (pointer) infolist_name (string) description (string) pointer_description (string) args_description (string)
weechat | hook_line | hook "line" | - | callback (pointer) buffer_type (integer) buffers (string, array_size: "num_buffers") num_buffers (integer) tags_count (integer) tags_array (string, array_size: "tags_count")
weechat | hook_modifier | hook "modifier" | - | callback (pointer) modifier (string)
weechat | hook_print | hook "print" | - | callback (pointer) buffer (pointer, hdata: "buffer") tags_count (integer) tags_array (string, array_size: "tags_count") message (string) strip_colors (integer)

weechat

hook_process

hook "process"

-

callback (pointer)
command (string)
options (hashtable)
detached (integer)
timeout (long)
child_read (integer, array_size: "3")
child_write (integer, array_size: "3")
child_pid (integer)
hook_fd (pointer, array_size: "3", hdata: "hook")
hook_timer (pointer, hdata: "hook")
buffer (string, array_size: "3")
buffer_size (integer, array_size: "3")
buffer_flush (integer)

weechat | hook_signal | hook "signal" | - | callback (pointer) signals (string, array_size: "num_signals") num_signals (integer)
weechat | hook_timer | hook "timer" | - | callback (pointer) interval (long) align_second (integer) remaining_calls (integer) last_exec (time) last_exec_usec (long) next_exec (time) next_exec_usec (long)
weechat | hook_url | hook "url" | - | callback (pointer) url (string) options (hashtable) timeout (long) thread_id (long) thread_created (integer) thread_running (integer) hook_timer (pointer, hdata: "hook") output (hashtable)
weechat | hotlist | hotlist | gui_hotlist last_gui_hotlist | priority (integer) time (time) time_usec (long) buffer (pointer, hdata: "buffer") count (integer, array_size: "4") prev_hotlist (pointer, hdata: "hotlist") next_hotlist (pointer, hdata: "hotlist")
weechat | input_undo | structure with undo for input line | - | data (string) pos (integer) prev_undo (pointer, hdata: "input_undo") next_undo (pointer, hdata: "input_undo")

weechat

key

a key (keyboard shortcut)

gui_default_keys
gui_default_keys_cursor
gui_default_keys_histsearch
gui_default_keys_mouse
gui_default_keys_search
gui_keys
gui_keys_cursor
gui_keys_histsearch
gui_keys_mouse
gui_keys_search
last_gui_default_key
last_gui_default_key_cursor
last_gui_default_key_histsearch
last_gui_default_key_mouse
last_gui_default_key_search
last_gui_key
last_gui_key_cursor
last_gui_key_histsearch
last_gui_key_mouse
last_gui_key_search

key (string)
area_type (pointer)
area_name (pointer)
area_key (string)
command (string)
score (integer)
prev_key (pointer, hdata: "key")
next_key (pointer, hdata: "key")

weechat | layout | layout | gui_layout_current gui_layouts last_gui_layout | name (string) layout_buffers (pointer, hdata: "layout_buffer") last_layout_buffer (pointer, hdata: "layout_buffer") layout_windows (pointer, hdata: "layout_window") internal_id (integer) internal_id_current_window (integer) prev_layout (pointer, hdata: "layout") next_layout (pointer, hdata: "layout")
weechat | layout_buffer | buffer layout | - | plugin_name (string) buffer_name (string) number (integer) prev_layout (pointer, hdata: "layout_buffer") next_layout (pointer, hdata: "layout_buffer")
weechat | layout_window | window layout | - | internal_id (integer) parent_node (pointer, hdata: "layout_window") split_pct (integer) split_horiz (integer) child1 (pointer, hdata: "layout_window") child2 (pointer, hdata: "layout_window") plugin_name (string) buffer_name (string)
weechat | line | structure with one line | - | data (pointer, hdata: "line_data") prev_line (pointer, hdata: "line") next_line (pointer, hdata: "line")

weechat

line_data

structure with one line data

-

buffer (pointer, hdata: "buffer")
id (integer)
y (integer)
date (time)
date_usec (integer)
date_printed (time)
date_usec_printed (integer)
str_time (string)
tags_count (integer)
tags_array (shared_string, array_size: "tags_count")
displayed (char)
notify_level (char)
highlight (char)
refresh_needed (char)
prefix (shared_string)
prefix_length (integer)
message (string)

Update allowed:
date (time)
date_usec (integer)
date_printed (time)
date_usec_printed (integer)
tags_array (shared_string)
prefix (shared_string)
message (string)

weechat | lines | structure with lines | - | first_line (pointer, hdata: "line") last_line (pointer, hdata: "line") last_read_line (pointer, hdata: "line") lines_count (integer) first_line_not_read (integer) lines_hidden (integer) buffer_max_length (integer) buffer_max_length_refresh (integer) prefix_max_length (integer) prefix_max_length_refresh (integer)
weechat | nick | nick in nicklist | - | id (longlong) group (pointer, hdata: "nick_group") name (shared_string) color (shared_string) prefix (shared_string) prefix_color (shared_string) visible (integer) prev_nick (pointer, hdata: "nick") next_nick (pointer, hdata: "nick")

weechat

nick_group

group in nicklist

-

id (longlong)
name (shared_string)
color (shared_string)
visible (integer)
level (integer)
parent (pointer, hdata: "nick_group")
children (pointer, hdata: "nick_group")
last_child (pointer, hdata: "nick_group")
nicks (pointer, hdata: "nick")
last_nick (pointer, hdata: "nick")
prev_group (pointer, hdata: "nick_group")
next_group (pointer, hdata: "nick_group")

weechat

plugin

plugin

weechat_plugins
last_weechat_plugin

filename (string)
handle (pointer)
name (string)
description (string)
author (string)
version (string)
license (string)
charset (string)
priority (integer)
initialized (integer)
debug (integer)
upgrading (integer)
unload_with_upgrade (integer)
variables (hashtable)
prev_plugin (pointer, hdata: "plugin")
next_plugin (pointer, hdata: "plugin")

weechat | proxy | proxy | weechat_proxies last_weechat_proxy | name (string) options (pointer) prev_proxy (pointer, hdata: "proxy") next_proxy (pointer, hdata: "proxy")

weechat

window

window

gui_current_window
gui_windows
last_gui_window

number (integer)
win_x (integer)
win_y (integer)
win_width (integer)
win_height (integer)
win_width_pct (integer)
win_height_pct (integer)
win_chat_x (integer)
win_chat_y (integer)
win_chat_width (integer)
win_chat_height (integer)
win_chat_cursor_x (integer)
win_chat_cursor_y (integer)
bar_windows (pointer, hdata: "bar_window")
last_bar_window (pointer, hdata: "bar_window")
refresh_needed (integer)
gui_objects (pointer)
buffer (pointer, hdata: "buffer")
layout_plugin_name (string)
layout_buffer_name (string)
scroll (pointer, hdata: "window_scroll")
scroll_changed (integer)
ptr_tree (pointer, hdata: "window_tree")
prev_window (pointer, hdata: "window")
next_window (pointer, hdata: "window")

weechat | window_scroll | scroll info in window | - | buffer (pointer, hdata: "buffer") first_line_displayed (integer) start_line (pointer, hdata: "line") start_line_pos (integer) scrolling (integer) start_col (integer) lines_after (integer) text_search_start_line (pointer, hdata: "line") prev_scroll (pointer, hdata: "window_scroll") next_scroll (pointer, hdata: "window_scroll")
weechat | window_tree | tree of windows | gui_windows_tree | parent_node (pointer, hdata: "window_tree") split_pct (integer) split_horizontal (integer) child1 (pointer, hdata: "window_tree") child2 (pointer, hdata: "window_tree") window (pointer, hdata: "window")

C 言語での使用例:

    struct t_hdata *hdata = weechat_hdata_get ("irc_server");

スクリプト (Python) での使用例:

    # プロトタイプ
    def hdata_get(hdata_name: str) -> str: ...

    # 例
    hdata = weechat.hdata_get("irc_server")

#### hdata_get_var_offset

WeeChat バージョン 0.3.6 以上で利用可。

hdata における変数のオフセットを返す。

プロトタイプ:

    int weechat_hdata_get_var_offset (struct t_hdata *hdata, const char *name);

引数:

- hdata: hdata へのポインタ

- name: 変数名

戻り値:

- オフセットの値、エラーが起きた場合は -1

C 言語での使用例:

    int offset = weechat_hdata_get_var_offset (hdata, "name");

スクリプト (Python) での使用例:

    # プロトタイプ
    def hdata_get_var_offset(hdata: str, name: str) -> int: ...

    # 例
    offset = weechat.hdata_get_var_offset(hdata, "name")

#### hdata_get_var_type

WeeChat バージョン 0.3.6 以上で利用可。

hdata 内の変数の型を (整数で) 返す。

プロトタイプ:

    int weechat_hdata_get_var_type (struct t_hdata *hdata, const char *name);

引数:

- hdata: hdata へのポインタ

- name: 変数名

戻り値:

- 変数の型、エラーが起きた場合は -1

C 言語での使用例:

    int type = weechat_hdata_get_var_type (hdata, "name");
    switch (type)
    {
        case WEECHAT_HDATA_CHAR:
            /* ... */
            break;
        case WEECHAT_HDATA_INTEGER:
            /* ... */
            break;
        case WEECHAT_HDATA_LONG:
            /* ... */
            break;
        case WEECHAT_HDATA_LONGLONG:
            /* ... */
            break;
        case WEECHAT_HDATA_STRING:
            /* ... */
            break;
        case WEECHAT_HDATA_SHARED_STRING:
            /* ... */
            break;
        case WEECHAT_HDATA_POINTER:
            /* ... */
            break;
        case WEECHAT_HDATA_TIME:
            /* ... */
            break;
        case WEECHAT_HDATA_HASHTABLE:
            /* ... */
            break;
        case WEECHAT_HDATA_OTHER:
            /* ... */
            break;
        default:
            /* variable not found */
            break;
    }

注記 | スクリプト API ではこの関数を利用できません。

#### hdata_get_var_type_string

WeeChat バージョン 0.3.6 以上で利用可。

変数の型を (文字列で) 返す。

プロトタイプ:

    const char *weechat_hdata_get_var_type_string (struct t_hdata *hdata, const char *name);

引数:

- hdata: hdata へのポインタ

- name: 変数名

戻り値:

- 変数の型、エラーが起きた場合は NULL

C 言語での使用例:

    weechat_printf (NULL, "type = %s", weechat_hdata_get_var_type_string (hdata, "name"));

スクリプト (Python) での使用例:

    # プロトタイプ
    def hdata_get_var_type_string(hdata: str, name: str) -> str: ...

    # 例
    weechat.prnt("", "type = %s" % weechat.hdata_get_var_type_string("name"))

#### hdata_get_var_array_size

WeeChat バージョン 0.3.9 以上で利用可。

hdata に含まれる配列変数のサイズを返す。

プロトタイプ:

    int weechat_hdata_get_var_array_size (struct t_hdata *hdata, void *pointer, const char *name);

引数:

- hdata: hdata へのポインタ

- pointer: WeeChat および plugin オブジェクトへのポインタ

- name: 変数名

戻り値:

- 配列変数のサイズ、配列変数でない場合とエラーが起きた場合は -1

C 言語での使用例:

    int array_size = weechat_hdata_get_var_array_size (hdata, pointer, "name");

スクリプト (Python) での使用例:

    # プロトタイプ
    def hdata_get_var_array_size(hdata: str, pointer: str, name: str) -> int: ...

    # 例
    array_size = weechat.hdata_get_var_array_size(hdata, pointer, "name")

#### hdata_get_var_array_size_string

WeeChat バージョン 0.3.9 以上で利用可。

hdata に含まれる配列変数のサイズを (文字列で) 返す。

プロトタイプ:

    const char *weechat_hdata_get_var_array_size_string (struct t_hdata *hdata, void *pointer,
                                                         const char *name);

引数:

- hdata: hdata へのポインタ

- pointer: WeeChat および plugin オブジェクトへのポインタ

- name: 変数名

戻り値:

- 配列変数のサイズの文字列、配列変数でない場合とエラーが起きた場合は NULL

C 言語での使用例:

    const char *array_size = weechat_hdata_get_var_array_size_string (hdata, pointer, "name");

スクリプト (Python) での使用例:

    # プロトタイプ
    def hdata_get_var_array_size_string(hdata: str, pointer: str, name: str) -> str: ...

    # 例
    array_size = weechat.hdata_get_var_array_size_string(hdata, pointer, "name")

#### hdata_get_var_hdata

WeeChat バージョン 0.3.6 以上で利用可。

hdata に含まれる変数に対応する hdata を返す。

プロトタイプ:

    const char *weechat_hdata_get_var_hdata (struct t_hdata *hdata, const char *name);

引数:

- hdata: hdata へのポインタ

- name: 変数名

戻り値:

- 変数に対応する、hdata がない場合とエラーが起きた場合は NULL

C 言語での使用例:

    weechat_printf (NULL, "hdata = %s", weechat_hdata_get_var_hdata (hdata, "name"));

スクリプト (Python) での使用例:

    # プロトタイプ
    def hdata_get_var_hdata(hdata: str, name: str) -> str: ...

    # 例
    weechat.prnt("", "hdata = %s" % weechat.hdata_get_var_hdata(hdata, "name"))

#### hdata_get_var

WeeChat バージョン 0.3.6 以上で利用可。

hdata に含まれる変数の内容へのポインタを返す。

プロトタイプ:

    void *weechat_hdata_get_var (struct t_hdata *hdata, void *pointer, const char *name);

引数:

- hdata: hdata へのポインタ

- pointer: WeeChat および plugin オブジェクトへのポインタ

- name: 変数名

戻り値:

- 変数の内容へのポインタ、エラーが起きた場合は NULL

C 言語での使用例:

    struct t_hdata *hdata = weechat_hdata_get ("buffer");
    struct t_gui_buffer *buffer = weechat_buffer_search_main ();
    void *pointer = weechat_hdata_get_var (hdata, buffer, "name");

注記 | スクリプト API ではこの関数を利用できません。

#### hdata_get_var_at_offset

WeeChat バージョン 0.3.6 以上で利用可。

オフセットを使って hdata に含まれる変数を指定し、この内容へのポインタを返す。

プロトタイプ:

    void *weechat_hdata_get_var_at_offset (struct t_hdata *hdata, void *pointer, int offset);

引数:

- hdata: hdata へのポインタ

- pointer: WeeChat および plugin オブジェクトへのポインタ

- name: 変数名

戻り値:

- 変数の内容へのポインタ、エラーが起きた場合は NULL

C 言語での使用例:

    struct t_hdata *hdata = weechat_hdata_get ("buffer");
    struct t_gui_buffer *buffer = weechat_buffer_search_main ();
    int offset = weechat_hdata_get_var_offset (hdata, "name");
    void *pointer = weechat_hdata_get_var_at_offset (hdata, buffer, offset);

注記 | スクリプト API ではこの関数を利用できません。

#### hdata_get_list

WeeChat バージョン 0.3.6 以上で利用可。

hdata からリストへのポインタを返す。

プロトタイプ:

    void *weechat_hdata_get_list (struct t_hdata *hdata, const char *name);

引数:

- hdata: hdata へのポインタ

- name: リスト名

戻り値:

- リストへのポインタ、エラーが起きた場合は NULL

C 言語での使用例:

    struct t_hdata *hdata = weechat_hdata_get ("buffer");
    struct t_gui_buffer *buffers = weechat_hdata_get_list (hdata, "gui_buffers");

スクリプト (Python) での使用例:

    # プロトタイプ
    def hdata_get_list(hdata: str, name: str) -> str: ...

    # 例
    hdata = weechat.hdata_get("buffer")
    buffers = weechat.hdata_get_list(hdata, "gui_buffers")

#### hdata_check_pointer

WeeChat バージョン 0.3.7 以上で利用可、バージョン 1.0 で更新。

hdata とリストへのポインタを使ってポインタの妥当性を確認する。

プロトタイプ:

    int weechat_hdata_check_pointer (struct t_hdata *hdata, void *list, void *pointer);

引数:

- hdata: hdata へのポインタ

- list: リストポインタ; NULL の場合 (WeeChat バージョン 1.0 以上)、ポインタは hdata に含まれる "check pointers" フラグを持つリストでチェックされます (hdata_new_list を参照)、このフラグを持つリストがない場合、ポインタは妥当とされます。

- pointer: 確認するポインタ

戻り値:

- リスト内にポインタが有る場合は 1、無い場合は 0

C 言語での使用例:

    /* check if a buffer pointer is valid */
    struct t_hdata *hdata = weechat_hdata_get ("buffer");
    if (weechat_hdata_check_pointer (hdata,
                                     weechat_hdata_get_list (hdata, "gui_buffers"),
                                     ptr_buffer))
    {
        /* valid pointer */
    }
    else
    {
        /* invalid pointer */
    }

スクリプト (Python) での使用例:

    # プロトタイプ
    def hdata_check_pointer(hdata: str, list: str, pointer: str) -> int: ...

    # 例
    hdata = weechat.hdata_get("buffer")
    if weechat.hdata_check_pointer(hdata, weechat.hdata_get_list(hdata, "gui_buffers"), ptr_buffer):
        # valid pointer
        # ...
    else:
        # invalid pointer
        # ...

#### hdata_move

WeeChat バージョン 0.3.6 以上で利用可。

リスト内の他の要素にポインタを移動する。

プロトタイプ:

    void *weechat_hdata_move (struct t_hdata *hdata, void *pointer, int count);

引数:

- hdata: hdata へのポインタ

- pointer: WeeChat および plugin オブジェクトへのポインタ

- count: 移動を実行する回数 (負および正の整数、ゼロは禁止)

戻り値:

- 移動に成功した場合は移動先へのポインタ、要素が見つからないかエラーが発生した場合 (例えばリストの最後に到達した場合) は NULL

C 言語での使用例:

    struct t_hdata *hdata = weechat_hdata_get ("buffer");
    struct t_gui_buffer *buffer = weechat_buffer_search_main ();

    /* バッファを次のバッファに 2 回移動 */
    buffer = weechat_hdata_move (hdata, buffer, 2);

    /* 1 つ前のバッファに移動 */
    if (buffer)
        buffer = weechat_hdata_move (hdata, buffer, -1);

スクリプト (Python) での使用例:

    # プロトタイプ
    def hdata_move(hdata: str, pointer: str, count: int) -> str: ...

    # 例
    hdata = weechat.hdata_get("buffer")
    buffer = weechat.buffer_search_main()

    # バッファを次のバッファに 2 回移動
    buffer = weechat.hdata_move(hdata, buffer, 2)

    # 1 つ前のバッファに移動
    if buffer:
        buffer = weechat.hdata_move(hdata, buffer, -1)

#### hdata_search

WeeChat バージョン 0.4.1 以上で利用可、バージョン 3.4 で更新。

リストから要素を検索: リスト内の各要素に対して search の内容を評価し、マッチする要素が見つかるかリストの最後に到達するまでこれを続ける。

プロトタイプ:

    void *weechat_hdata_search (struct t_hdata *hdata, void *pointer, const char *search,
                                struct t_hashtable *pointers, struct t_hashtable *extra_vars,
                                struct t_hashtable *options, int move);

引数:

- hdata: hdata へのポインタ

- pointer: WeeChat および plugin オブジェクトへのポインタ

- search: 評価する式、式中のデフォルトポインタは hdata の名前 (デフォルトポインタはリストに含まれる各要素で置換されます); 式に関する詳細は WeeChat ユーザーズガイド / WeeChat コマンド / eval ↗ を参照してください

- pointers: 関数に渡されるハッシュテーブル string_eval_expression

- extra_vars: 関数に渡されるハッシュテーブル string_eval_expression

- options: 関数に渡されるハッシュテーブル string_eval_expression

- move: 検索に失敗した後に移動を実行する回数 (負および正の整数、ゼロは禁止)

重要 | You must ensure the search expression is safe and does not include any user data. Such unsafe data must be given in the hashtable extra_vars and referenced by `${xxx}` in the search expression (see the example below).

戻り値:

- 見つかった要素へのポインタ、見つからなかった場合は NULL

C 言語での使用例:

    struct t_hdata *hdata = weechat_hdata_get ("irc_server");
    void *servers = weechat_hdata_get_list (hdata, "irc_servers");
    struct t_hashtable *extra_vars = weechat_hashtable_new (8,
                                                            WEECHAT_HASHTABLE_STRING,
                                                            WEECHAT_HASHTABLE_STRING,
                                                            NULL,
                                                            NULL);

    /* search irc server with name "libera" */
    weechat_hashtable_set (extra_vars, "server_name", "libera");
    void *server = weechat_hdata_search (hdata, servers, "${irc_server.name} == ${server_name}",
                                         NULL, extra_vars, NULL, 1);
    if (server)
    {
        /* ... */
    }
    weechat_hashtable_free (extra_vars);

スクリプト (Python) での使用例:

    # プロトタイプ
    def hdata_search(hdata: str, pointer: str, search: str,
                     pointers: Dict[str, str], extra_vars: Dict[str, str], options: Dict[str, str],
                     count: int) -> str: ...

    # 例
    hdata = weechat.hdata_get("irc_server")
    servers = weechat.hdata_get_list(hdata, "irc_servers")

    # search irc server with name "libera"
    server = weechat.hdata_search(hdata, servers, "${irc_server.name} == ${server_name}",
                                  {}, {"server_name": "libera"}, {}, 1)
    if server:
        # ...

#### hdata_char

WeeChat バージョン 0.3.7 以上で利用可。

hdata を使って構造体に含まれる文字型変数の値を返す。

プロトタイプ:

    char weechat_hdata_char (struct t_hdata *hdata, void *pointer, const char *name);

引数:

- hdata: hdata へのポインタ

- pointer: WeeChat および plugin オブジェクトへのポインタ

- name: 変数名 (必ず「文字型」であること); 配列の場合、"N|name" のように名前を指定することが可能。ここで N は配列のインデックス (1 番目は 0)、例: "2|name"

戻り値:

- 文字型変数の値

C 言語での使用例:

    weechat_printf (NULL, "letter = %c", weechat_hdata_char (hdata, pointer, "letter"));

スクリプト (Python) での使用例:

    # プロトタイプ
    def hdata_char(hdata: str, pointer: str, name: str) -> int: ...

    # 例
    weechat.prnt("", "letter = %c" % weechat.hdata_char(hdata, pointer, "letter"))

#### hdata_integer

WeeChat バージョン 0.3.6 以上で利用可。

hdata を使って構造体に含まれる整数型変数の値を返す。

プロトタイプ:

    int weechat_hdata_integer (struct t_hdata *hdata, void *pointer, const char *name);

引数:

- hdata: hdata へのポインタ

- pointer: WeeChat および plugin オブジェクトへのポインタ

- name: 変数名 (必ず「整数型」であること); 配列の場合、"N|name" のように名前を指定することが可能。ここで N は配列のインデックス (1 番目は 0)、例: "2|name"

戻り値:

- 整数型変数の値

C 言語での使用例:

    struct t_hdata *hdata = weechat_hdata_get ("buffer");
    struct t_gui_buffer *buffer = weechat_buffer_search_main ();
    weechat_printf (NULL, "number = %d", weechat_hdata_integer (hdata, buffer, "number"));

スクリプト (Python) での使用例:

    # プロトタイプ
    def hdata_integer(hdata: str, pointer: str, name: str) -> int: ...

    # 例
    hdata = weechat.hdata_get("buffer")
    buffer = weechat.buffer_search_main()
    weechat.prnt("", "number = %d" % weechat.hdata_integer(hdata, buffer, "number"))

#### hdata_long

WeeChat バージョン 0.3.6 以上で利用可。

hdata を使って構造体に含まれる "long" 型変数の値を返す。

プロトタイプ:

    long weechat_hdata_long (struct t_hdata *hdata, void *pointer, const char *name);

引数:

- hdata: hdata へのポインタ

- pointer: WeeChat および plugin オブジェクトへのポインタ

- name: 変数名 (必ず「long 型」であること); 配列の場合、"N|name" のように名前を指定することが可能。ここで N は配列のインデックス (1 番目は 0)、例: "2|name"

戻り値:

- long 変数の値

C 言語での使用例:

    weechat_printf (NULL, "longvar = %ld", weechat_hdata_long (hdata, pointer, "longvar"));

スクリプト (Python) での使用例:

    # プロトタイプ
    def hdata_long(hdata: str, pointer: str, name: str) -> int: ...

    # 例
    weechat.prnt("", "longvar = %d" % weechat.hdata_long(hdata, pointer, "longvar"))

#### hdata_longlong

WeeChat バージョン 4.3.0 以上で利用可。

Return value of "long long" variable in structure using hdata.

プロトタイプ:

    long long weechat_hdata_longlong (struct t_hdata *hdata, void *pointer, const char *name);

引数:

- hdata: hdata へのポインタ

- pointer: WeeChat および plugin オブジェクトへのポインタ

- name: 変数名 (必ず「long long 型」であること); 配列の場合、"N|name" のように名前を指定することが可能。ここで N は配列のインデックス (1 番目は 0)、例: "2|name"

戻り値:

- "long long" value of variable

C 言語での使用例:

    weechat_printf (NULL, "longlongvar = %lld", weechat_hdata_longlong (hdata, pointer, "longlongvar"));

スクリプト (Python) での使用例:

    # プロトタイプ
    def hdata_longlong(hdata: str, pointer: str, name: str) -> int: ...

    # 例
    weechat.prnt("", "longlongvar = %d" % weechat.hdata_longlong(hdata, pointer, "longlongvar"))

#### hdata_string

WeeChat バージョン 0.3.6 以上で利用可。

hdata を使って構造体に含まれる文字列型変数の値を返す。

プロトタイプ:

    const char *weechat_hdata_string (struct t_hdata *hdata, void *pointer, const char *name);

引数:

- hdata: hdata へのポインタ

- pointer: WeeChat および plugin オブジェクトへのポインタ

- name: 変数名 (必ず「文字列型」であること); 配列の場合、"N|name" のように名前を指定することが可能。ここで N は配列のインデックス (1 番目は 0)、例: "2|name"

戻り値:

- 文字列変数の値

C 言語での使用例:

    struct t_hdata *hdata = weechat_hdata_get ("buffer");
    struct t_gui_buffer *buffer = weechat_buffer_search_main ();
    weechat_printf (NULL, "name = %s", weechat_hdata_string (hdata, buffer, "name"));

スクリプト (Python) での使用例:

    # プロトタイプ
    def hdata_string(hdata: str, pointer: str, name: str) -> str: ...

    # 例
    hdata = weechat.hdata_get("buffer")
    buffer = weechat.buffer_search_main()
    weechat.prnt("", "name = %s" % weechat.hdata_string(hdata, buffer, "name"))

#### hdata_pointer

WeeChat バージョン 0.3.6 以上で利用可。

hdata を使って構造体に含まれるポインタ型変数の値を返す。

プロトタイプ:

    void *weechat_hdata_pointer (struct t_hdata *hdata, void *pointer, const char *name);

引数:

- hdata: hdata へのポインタ

- pointer: WeeChat および plugin オブジェクトへのポインタ

- name: 変数名 (必ず「ポインタ型」であること); 配列の場合、"N|name" のように名前を指定することが可能。ここで N は配列のインデックス (1 番目は 0)、例: "2|name"

戻り値:

- ポインタ型変数の値

C 言語での使用例:

    struct t_hdata *hdata = weechat_hdata_get ("buffer");
    struct t_gui_buffer *buffer = weechat_buffer_search_main ();
    weechat_printf (NULL, "lines = %p", weechat_hdata_pointer (hdata, buffer, "lines"));

スクリプト (Python) での使用例:

    # プロトタイプ
    def hdata_pointer(hdata: str, pointer: str, name: str) -> str: ...

    # 例
    hdata = weechat.hdata_get("buffer")
    buffer = weechat.buffer_search_main()
    weechat.prnt("", "lines = %x" % weechat.hdata_pointer(hdata, buffer, "lines"))

#### hdata_time

WeeChat バージョン 0.3.6 以上で利用可。

hdata を使って構造体に含まれる時刻型変数の値を返す。

プロトタイプ:

    time_t weechat_hdata_time (struct t_hdata *hdata, void *pointer, const char *name);

引数:

- hdata: hdata へのポインタ

- pointer: WeeChat および plugin オブジェクトへのポインタ

- name: 変数名 (必ず「時刻型」であること); 配列の場合、"N|name" のように名前を指定することが可能。ここで N は配列のインデックス (1 番目は 0)、例: "2|name"

戻り値:

- 時刻型変数の値

C 言語での使用例:

    struct t_hdata *hdata = weechat_hdata_get ("buffer");
    struct t_gui_buffer *ptr = weechat_buffer_search_main ();
    ptr = weechat_hdata_pointer (hdata, ptr, "lines");
    if (ptr)
    {
        hdata = weechat_hdata_get ("lines");
        ptr = weechat_hdata_pointer (hdata, ptr, "first_line");
        if (ptr)
        {
            hdata = weechat_hdata_get ("line");
            ptr = weechat_hdata_pointer (hdata, ptr, "data");
            if (ptr)
            {
                hdata = weechat_hdata_get ("line_data");
                time_t date = weechat_hdata_time (hdata, hdata, "date");
                weechat_printf (NULL, "time of last line displayed = %s", ctime (&date));
            }
        }
    }

スクリプト (Python) での使用例:

    # プロトタイプ
    def hdata_time(hdata: str, pointer: str, name: str) -> int: ...

    # 例
    buf = weechat.buffer_search_main()
    ptr = weechat.hdata_pointer(weechat.hdata_get("buffer"), buf, "lines")
    if ptr:
        ptr = weechat.hdata_pointer(weechat.hdata_get("lines"), ptr, "first_line")
        if ptr:
            ptr = weechat.hdata_pointer(weechat.hdata_get("line"), ptr, "data")
            if ptr:
                date = weechat.hdata_time(weechat.hdata_get("line_data"), ptr, "date")
                weechat.prnt("", "time of first line displayed = %s" % time.strftime("%F %T", time.localtime(int(date))))

#### hdata_hashtable

WeeChat バージョン 0.3.7 以上で利用可。

hdata を使って構造体に含まれるハッシュテーブル型変数の値を返す。

プロトタイプ:

    struct t_hashtable *weechat_hdata_hashtable (struct t_hdata *hdata, void *pointer, const char *name);

引数:

- hdata: hdata へのポインタ

- pointer: WeeChat および plugin オブジェクトへのポインタ

- name: 変数名 (必ず「ハッシュテーブル型」であること); 配列の場合、"N|name" のように名前を指定することが可能。ここで N は配列のインデックス (1 番目は 0)、例: "2|name"

戻り値:

- ハッシュテーブル型変数の値 (ハッシュテーブルへのポインタ)

C 言語での使用例:

    struct t_hdata *hdata = weechat_hdata_get ("buffer");
    struct t_gui_buffer *buffer = weechat_buffer_search_main ();
    struct t_hashtable *hashtable = weechat_hdata_hashtable (hdata, buffer, "local_variables");
    weechat_printf (NULL, "%d local variables in core buffer",
                    weechat_hashtable_get_integer (hashtable, "items_count"));

スクリプト (Python) での使用例:

    # プロトタイプ
    def hdata_hashtable(hdata: str, pointer: str, name: str) -> Dict[str, str]: ...

    # 例
    hdata = weechat.hdata_get("buffer")
    buffer = weechat.buffer_search_main()
    hash = weechat.hdata_hashtable(hdata, buffer, "local_variables")
    weechat.prnt("", "local variables in core buffer:")
    for key in hash:
        weechat.prnt("", "  %s == %s" % (key, hash[key]))

#### hdata_compare

WeeChat ≥ 1.9, updated in 4.1.0.

2 つのオブジェクトの hdata 変数を比較。

プロトタイプ:

    int weechat_hdata_compare (struct t_hdata *hdata, void *pointer1, void *pointer2, const char *name, int case_sensitive);

引数:

- hdata: hdata へのポインタ

- pointer1: 1 番目の WeeChat およびプラグインオブジェクトへのポインタ

- pointer2: 2 番目の WeeChat およびプラグインオブジェクトへのポインタ

- name: variable name or path to a variable name; 配列の場合、変数名を "N|name" のように指定できます。ここで N は配列のインデックス番号です (番号は 0 から始まります)。例: "2|name"

- case_sensitive: 大文字小文字を区別する場合 1、それ以外の場合 0

戻り値:

- variable1 < variable2 の場合は -1

- variable1 == variable2 の場合は 0

- variable1 > variable2 の場合は 1

C 言語での使用例:

    struct t_hdata *hdata = weechat_hdata_get ("buffer");
    struct t_gui_buffer *buffer1 = weechat_buffer_search ("irc", "libera.#weechat");
    struct t_gui_buffer *buffer2 = weechat_buffer_search ("irc", "libera.#weechat-fr");
    weechat_printf (NULL, "comparison of buffer number = %d",
                    weechat_hdata_compare (hdata, buffer1, buffer2, "number", 0));
    weechat_printf (NULL, "comparison of number of lines = %d",
                    weechat_hdata_compare (hdata, buffer1, buffer2, "own_lines.lines_count", 0));
    weechat_printf (NULL, "comparison of local variable = %d",
                    weechat_hdata_compare (hdata, buffer1, buffer2, "local_variables.myvar", 0));

スクリプト (Python) での使用例:

    # プロトタイプ
    def hdata_compare(hdata: str, pointer1: str, pointer2: str, name: str, case_sensitive: int) -> int: ...

    # 例
    hdata = weechat.hdata_get("buffer")
    buffer1 = weechat.buffer_search("irc", "libera.#weechat")
    buffer2 = weechat.buffer_search("irc", "libera.#weechat-fr")
    weechat.prnt("", "comparison of buffer number = %d" % weechat.hdata_compare(hdata, buffer1, buffer2, "number", 0))
    weechat.prnt("", "comparison of number of lines = %d" % weechat.hdata_compare(hdata, buffer1, buffer2, "own_lines.lines_count", 0))
    weechat.prnt("", "comparison of local variable = %d" % weechat.hdata_compare(hdata, buffer1, buffer2, "local_variables.myvar", 0))

#### hdata_set

WeeChat バージョン 0.3.9 以上で利用可。

hdata の変数に新しい値を設定。

注記 | 変数の更新を許可している場合に、この関数呼び出して良いのは update コールバックの中だけです (hdata_new と hdata_update を参照)

プロトタイプ:

    int weechat_hdata_set (struct t_hdata *hdata, void *pointer, const char *name, const char *value);

引数:

- hdata: hdata へのポインタ

- pointer: WeeChat および plugin オブジェクトへのポインタ

- name: 変数名 (許可されている型: 文字型、整数型、long 型、文字列型、ポインタ型、時刻型)

- value: 変数の新しい値

戻り値:

- 成功した場合は 1、エラーが起きた場合は 0

C 言語での使用例:

    weechat_hdata_set (hdata, pointer, "message", "test");

注記 | スクリプト API ではこの関数を利用できません。

#### hdata_update

WeeChat バージョン 0.3.9 以上で利用可。

hdata 内のデータを更新。

プロトタイプ:

    int weechat_hdata_update (struct t_hdata *hdata, void *pointer, struct t_hashtable *hashtable);

引数:

- hdata: hdata へのポインタ

- pointer: WeeChat および plugin オブジェクトへのポインタ

- hashtable: 更新する変数: キーは変数の名前、値は変数の新しい値 (キーと値は文字列)、以下の特別なキーを使うことができます:

  - キー `__create_allowed` (値は任意): 構造体の作製を許可する場合は 1、許可しない場合は 0 を返す (WeeChat バージョン 0.4.0 以上で利用可)

  - キー `__delete_allowed` (値は任意): 構造体の削除を許可する場合は 1、許可しない場合は 0 を返す

  - キー `__update_allowed`、値は変数の名前: この変数の更新を許可する場合は 1、許可しない場合は 0 を返す

  - キー `__delete` (値は任意): 構造体を削除 (許可されている場合)

戻り値:

- 更新された変数の個数

C 言語での使用例:

    /* 現在のバッファに表示されている最後のメッセージの時間を 1 時間前にする */

    struct t_gui_lines *own_lines;
    struct t_gui_line *line;
    struct t_gui_line_data *line_data;
    struct t_hdata *hdata;
    struct t_hashtable *hashtable;
    char str_date[64];

    own_lines = weechat_hdata_pointer (weechat_hdata_get ("buffer"), weechat_current_buffer (), "own_lines");
    if (own_lines)
    {
        line = weechat_hdata_pointer (weechat_hdata_get ("lines"), own_lines, "last_line");
        if (line)
        {
            line_data = weechat_hdata_pointer (weechat_hdata_get ("line"), line, "data");
            hdata = weechat_hdata_get ("line_data");
            hashtable = weechat_hashtable_new (8,
                                               WEECHAT_HASHTABLE_STRING,
                                               WEECHAT_HASHTABLE_STRING,
                                               NULL,
                                               NULL);
            if (hashtable)
            {
                snprintf (str_date, sizeof (str_date), "%ld", ((long int)weechat_hdata_time (hdata, line_data, "date")) - 3600);
                weechat_hashtable_set (hashtable, "date", str_date);
                weechat_hdata_update (hdata, line_data, hashtable);
                weechat_hashtable_free (hashtable);
            }
        }
    }

スクリプト (Python) での使用例:

    # プロトタイプ
    def hdata_update(hdata: str, pointer: str, hashtable: Dict[str, str]) -> int: ...

    # 例: 現在のバッファに表示されている最後のメッセージの時間を 1 時間前にする
    own_lines = weechat.hdata_pointer(weechat.hdata_get("buffer"), weechat.current_buffer(), "own_lines")
    if own_lines:
        line = weechat.hdata_pointer(weechat.hdata_get("lines"), own_lines, "last_line")
        if line:
            line_data = weechat.hdata_pointer(weechat.hdata_get("line"), line, "data")
            hdata = weechat.hdata_get("line_data")
            weechat.hdata_update(hdata, line_data, {"date": str(weechat.hdata_time(hdata, line_data, "date") - 3600)})

#### hdata_get_string

WeeChat バージョン 0.3.6 以上で利用可。

hdata プロパティの文字列値を返す。

プロトタイプ:

    const char *weechat_hdata_get_string (struct t_hdata *hdata, const char *property);

引数:

- hdata: hdata へのポインタ

- property: プロパティ名:

  - var_keys: hdata に含まれる変数のキーのリストを含む文字列 (書式: "key1,key2,key3")

  - var_values: hdata に含まれる変数の値のリストを含む文字列 (書式: "value1,value2,value3")

  - var_keys_values: hdata に含まれる変数のキーと値のリストを含む文字列 (書式: "key1:value1,key2:value2,key3:value3")

  - var_prev: 構造体に含まれる変数の名前、構造体はリスト内の 1 つ前の要素へのポインタ

  - var_next: 構造体に含まれる変数の名前、構造体はリスト内の 1 つ後の要素へのポインタ

  - list_keys: hdata に含まれるリストのキーのリストを含む文字列 (書式: "key1,key2,key3")

  - list_values: hdata に含まれるリストの値のリストを含む文字列 (書式: "value1,value2,value3")

  - list_keys_values: hdata に含まれるリストのキーと値のリストを含む文字列 (書式: "key1:value1,key2:value2,key3:value3")

戻り値:

- プロパティの文字列値

C 言語での使用例:

    weechat_printf (NULL, "variables in hdata: %s", weechat_hdata_get_string (hdata, "var_keys"));
    weechat_printf (NULL, "lists in hdata: %s", weechat_hdata_get_string (hdata, "list_keys"));

スクリプト (Python) での使用例:

    # プロトタイプ
    def hdata_get_string(hdata: str, property: str) -> str: ...

    # 例
    weechat.prnt("", "variables in hdata: %s" % weechat.hdata_get_string(hdata, "var_keys"))
    weechat.prnt("", "lists in hdata: %s" % weechat.hdata_get_string(hdata, "list_keys"))

### 3.26. アップグレード

WeeChat をアップグレードする (コマンド "/upgrade") 関数。

#### upgrade_new

WeeChat バージョン 1.5 で更新。

アップグレード用のファイルを作成またはロード。

プロトタイプ:

    struct t_upgrade_file *upgrade_file_new (const char *filename,
                                             int (*callback_read)(const void *pointer,
                                                                  void *data,
                                                                  struct t_upgrade_file *upgrade_file,
                                                                  int object_id,
                                                                  struct t_infolist *infolist),
                                             const void *callback_read_pointer,
                                             void *callback_read_data);

引数:

- filename: ファイルの名前 (WeeChat はこの名前に拡張子 ".upgrade" を追加します)

- callback_read: アップグレードファイル内の各オブジェクトを読み込む際に呼び出すコールバック関数 引数と戻り値:

  - const void *pointer: ポインタ

  - void *data: ポインタ

  - struct t_upgrade_file *upgrade_file: アップグレードファイルへのポインタ

  - int object_id: オブジェクトの識別番号

  - struct t_infolist *infolist: オブジェクトの内容を含むインフォリスト

  - 戻り値:

    - WEECHAT_RC_OK

    - WEECHAT_RC_ERROR

- callback_read_pointer: WeeChat が callback_read コールバックを呼び出す際にコールバックに渡すポインタ

- callback_read_data: WeeChat が callback_read コールバックを呼び出す際にコールバックに渡すポインタ; このポインタが NULL でない場合、このポインタは malloc (または類似の関数) によって割り当てられたものでなければいけません。さらに、このポインタはアップグレードファイルが閉じられた時点で自動的に開放されます

戻り値:

- アップグレードファイルへのポインタ

C 言語での使用例:

    struct t_upgrade_file *upgrade_file = weechat_upgrade_new ("my_file",
                                                               NULL, NULL, NULL);

スクリプト (Python) での使用例:

    # プロトタイプ
    def upgrade_new(filename: str, callback_read: str, callback_read_data: str) -> str: ...

    # 例
    upgrade_file = weechat.upgrade_new("my_file", "", "")

#### upgrade_write_object

アップグレードファイルにオブジェクトを書き込む。

プロトタイプ:

    int weechat_upgrade_write_object (struct t_upgrade_file *upgrade_file,
                                      int object_id,
                                      struct t_infolist *infolist);

引数:

- upgrade_file: アップグレードファイルへのポインタ

- object_id: オブジェクトの識別番号

- infolist: ファイルに書き込むインフォリスト

戻り値:

- 成功した場合は 1、エラーが起きた場合は 0

C 言語での使用例:

    if (weechat_upgrade_write_object (upgrade_file, 1, &infolist))
    {
        /* OK */
    }
    else
    {
        /* error */
    }

スクリプト (Python) での使用例:

    # プロトタイプ
    def upgrade_write_object(upgrade_file: str, object_id: int, infolist: str) -> int: ...

    # 例
    weechat.upgrade_write_object(upgrade_file, 1, infolist)

#### upgrade_read

WeeChat バージョン 1.5 で更新。

アップグレードファイルを読み込む。

プロトタイプ:

    int weechat_upgrade_read (struct t_upgrade_file *upgrade_file);

引数:

- upgrade_file: アップグレードファイルへのポインタ

戻り値:

- 成功した場合は 1、エラーが起きた場合は 0

C 言語での使用例:

    weechat_upgrade_read (upgrade_file);

スクリプト (Python) での使用例:

    # プロトタイプ
    def upgrade_read(upgrade_file: str) -> int: ...

    # 例
    weechat.upgrade_read(upgrade_file)

#### upgrade_close

アップグレードファイルを閉じる。

プロトタイプ:

    void weechat_upgrade_close (struct t_upgrade_file *upgrade_file);

引数:

- upgrade_file: アップグレードファイルへのポインタ

C 言語での使用例:

    weechat_upgrade_close (upgrade_file);

スクリプト (Python) での使用例:

    # プロトタイプ
    def upgrade_close(upgrade_file: str) -> int: ...

    # 例
    weechat.upgrade_close(upgrade_file)