翻訳者:

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

この文書の最新版を見るには以下のページを確認して下さい: https://weechat.org/doc

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

2.2.1. 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 のデフォルトプラグインは以下の順番で初期化されます:

  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 (4007)

  14. javascript (4006)

  15. lua (4005)

  16. perl (4004)

  17. php (4003)

  18. python (4002)

  19. ruby (4001)

  20. tcl (4000)

  21. script (3000)

  22. fset (2000)

2.2.2. 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.

3.1.1. 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. プラグイン

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

3.2.1. 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 とロケールに準じて取り扱うようになっているからです。

3.3.1. 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")

3.3.2. 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: é à")

3.3.3. 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: é à")

3.3.4. 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")

3.3.5. 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) -> str: ...

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

3.3.6. 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 ではこの関数を利用できません。

3.3.7. 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 counter 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 ではこの関数を利用できません。

3.3.8. string_tolower

UTF-8 文字列を小文字に変換。

プロトタイプ:

void weechat_string_tolower (char *string);

引数:

  • string: 変換元の文字列

C 言語での使用例:

char str[] = "AbCdé";
weechat_string_tolower (str);  /* str is now: "abcdé" */
スクリプト API ではこの関数を利用できません。

3.3.9. string_toupper

UTF-8 文字列を大文字に変換。

プロトタイプ:

void weechat_string_toupper (char *string);

引数:

  • string: 変換元の文字列

C 言語での使用例:

char str[] = "AbCdé";
weechat_string_toupper (str);  /* str is now: "ABCDé" */
スクリプト API ではこの関数を利用できません。

3.3.10. strcasecmp

WeeChat バージョン 1.0 で更新。

ロケールと大文字小文字を無視して文字列を比較。

プロトタイプ:

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

引数:

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

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

戻り値:

  • string1 < string2 の場合は -1

  • string1 == string2 の場合は 0

  • string1 > string2 の場合は 1

C 言語での使用例:

int diff = weechat_strcasecmp ("aaa", "CCC");  /* == -2 */
スクリプト API ではこの関数を利用できません。

3.3.11. strcasecmp_range

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

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

プロトタイプ:

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

引数:

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

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

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

    • 26: A-Za-z のように変換して比較

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

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

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

戻り値:

  • string1 < string2 の場合は -1

  • string1 == string2 の場合は 0

  • string1 > string2 の場合は 1

C 言語での使用例:

int diff = weechat_strcasecmp_range ("nick{away}", "NICK[away]", 29);  /* == 0 */
スクリプト API ではこの関数を利用できません。

3.3.12. strncasecmp

WeeChat バージョン 1.0 で更新。

ロケールと大文字小文字を無視して max 文字だけ文字列を比較。

プロトタイプ:

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

引数:

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

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

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

戻り値:

  • string1 < string2 の場合は -1

  • string1 == string2 の場合は 0

  • string1 > string2 の場合は 1

C 言語での使用例:

int diff = weechat_strncasecmp ("aabb", "aacc", 2);  /* == 0 */
スクリプト API ではこの関数を利用できません。

3.3.13. strncasecmp_range

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

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

プロトタイプ:

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

引数:

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

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

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

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

    • 26: A-Za-z のように変換して比較

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

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

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

戻り値:

  • string1 < string2 の場合は -1

  • string1 == string2 の場合は 0

  • string1 > string2 の場合は 1

C 言語での使用例:

int diff = weechat_strncasecmp_range ("nick{away}", "NICK[away]", 6, 29);  /* == 0 */
スクリプト API ではこの関数を利用できません。

3.3.14. strcmp_ignore_chars

WeeChat バージョン 1.0 で更新。

一部の文字列を無視して、ロケールに依存して (オプションで大文字小文字の区別をしない) 文字列を比較。

プロトタイプ:

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

戻り値:

  • string1 < string2 の場合は -1

  • string1 == string2 の場合は 0

  • string1 > string2 の場合は 1

C 言語での使用例:

int diff = weechat_strcmp_ignore_chars ("a-b", "--a-e", "-", 1);  /* == -3 */
スクリプト API ではこの関数を利用できません。

3.3.15. strcasestr

WeeChat バージョン 1.3 で更新。

ロケールと大文字小文字を区別して文字列を検索。

プロトタイプ:

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 ではこの関数を利用できません。

3.3.16. strlen_screen

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

UTF-8 文字列を画面上に表示するために必要な画面幅を返す。非表示文字を 1 文字として数えます (これが 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

3.3.17. string_match

WeeChat バージョン 1.0 で更新。

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

プロトタイプ:

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

引数:

  • string: 文字列

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

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

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

戻り値:

  • マスクにマッチした場合は 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

3.3.18. string_match_list

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

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

プロトタイプ:

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

引数:

  • string: 文字列

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

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

戻り値:

  • 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

3.3.19. 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 ではこの関数を利用できません。

3.3.20. 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"

3.3.21. 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 ではこの関数を利用できません。

3.3.22. 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 ではこの関数を利用できません。

3.3.23. 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 ではこの関数を利用できません。

3.3.24. 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"

3.3.25. 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 ではこの関数を利用できません。

3.3.26. 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 ではこの関数を利用できません。

3.3.27. 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

3.3.28. 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

3.3.29. string_replace

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

プロトタイプ:

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

引数:

  • string: 文字列

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

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

戻り値:

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

C 言語での使用例:

char *str = weechat_string_replace ("test", "s", "x");  /* result: "text" */
/* ... */
free (str);
スクリプト API ではこの関数を利用できません。

3.3.30. 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 ではこの関数を利用できません。

3.3.31. 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 ではこの関数を利用できません。

3.3.32. string_split_shell

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

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

この関数は Python クラス "shlex" の C 言語実装です (ファイル: Python リポジトリの Lib/shlex.py)、参照: https://docs.python.org/3/library/shlex.html

プロトタイプ:

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 ではこの関数を利用できません。

3.3.33. 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 ではこの関数を利用できません。

3.3.34. string_build_with_split_string

分割文字列から文字列を作る。

プロトタイプ:

char *weechat_string_build_with_split_string (char **split_string,
                                              const char *separator);

引数:

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

  • separator: 文字列を分割する区切り文字

戻り値:

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

C 言語での使用例:

char **argv;
int argc;
argv = weechat_string_split ("abc def ghi", " ", 0, 0, &argc);
char *str = weechat_string_build_with_split_string (argv, ";");
/* str == "abc;def;ghi" */
/* ... */
free (str);
スクリプト API ではこの関数を利用できません。

3.3.35. string_split_command

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

プロトタイプ:

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

引数:

  • command: 分割するコマンド

  • separator: 区切り文字

戻り値:

  • 文字列の配列、分割に失敗した場合は NULL (使用後には必ず 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 ではこの関数を利用できません。

3.3.36. string_free_split_command

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

プロトタイプ:

void weechat_string_free_split_command (char **split_command);

引数:

C 言語での使用例:

char **argv = weechat_string_split_command ("/command1 arg;/command2", ';');
/* ... */
weechat_free_split_command (argv);
スクリプト API ではこの関数を利用できません。

3.3.37. 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"

3.3.38. 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

3.3.39. string_remove_color

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

プロトタイプ:

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

引数:

  • string: 文字列

  • replacement: NULL または空文字列でなければ、WeeChat 色コードを指定した文字列の 1 文字目で置換、そうでなければ WeeChat 色コードとそれに続く (色に関連する) 文字を文字列から削除

戻り値:

  • 色コードを削除した文字列 (使用後には必ず "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, "?");
/* ... */
free (str);

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

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

# 例
str = weechat.string_remove_color(my_string, "?")

3.3.40. string_base_encode

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

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

プロトタイプ:

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

引数:

  • base: 16、32、64

  • 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 ではこの関数を利用できません。

3.3.41. string_base_decode

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

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

プロトタイプ:

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

引数:

  • base: 16、32、64

  • 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 ではこの関数を利用できません。

3.3.42. 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 ではこの関数を利用できません。

3.3.43. 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

3.3.44. 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"

3.3.45. 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 and 3.4.

式を評価して文字列として返す。${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:xxx}

3.1

Raw string (not evaluated).

>> ${raw:${info:version}}
== ${info:version}

${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_cache_dir} or ${weechat_runtime_dir}.

>> ${weechat_config_dir}
== /home/user/.config/weechat

>> ${weechat_data_dir}
== /home/user/.local/share/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}
== ©

${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

現在の日付/時刻、カスタム書式を使うことも可能です (man strftime を参照)、 デフォルト書式は %F %T

>> ${date}
== 2015-06-30 19:02:45

>> ${date:%H:%M:%S}
== 19:02:45

${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

${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 の値 (windowbuffer ポインタはデフォルトで現在のウィンドウ/バッファに設定されます), list can be a list name (example: "gui_buffers"), a pointer (example: "0x1234abcd") or a pointer name (example: "my_pointer").

>> ${buffer[gui_buffers].full_name}
== core.weechat

>> ${buffer[my_buffer_pointer].full_name}
== core.weechat

>> ${window.buffer.number}
== 1

3.3.46. 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 ではこの関数を利用できません。

3.3.47. 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 ではこの関数を利用できません。

3.3.48. 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 ではこの関数を利用できません。

3.3.49. 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 ではこの関数を利用できません。

3.4. UTF-8

UTF-8 文字列関数。

3.4.1. 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 ではこの関数を利用できません。

3.4.2. 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 ではこの関数を利用できません。

3.4.3. utf8_normalize

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

プロトタイプ:

void weechat_utf8_normalize (char *string, char replacement);

引数:

  • string: 文字列

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

C 言語での使用例:

weechat_utf8_normalize (string, '?');
スクリプト API ではこの関数を利用できません。

3.4.4. 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 ではこの関数を利用できません。

3.4.5. 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 ではこの関数を利用できません。

3.4.6. 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 ではこの関数を利用できません。

3.4.7. 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 ではこの関数を利用できません。

3.4.8. 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 ではこの関数を利用できません。

3.4.9. 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 ではこの関数を利用できません。

3.4.10. 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 ではこの関数を利用できません。

3.4.11. utf8_charcmp

WeeChat バージョン 1.0 で更新。

2 つの UTF-8 文字を比較。

プロトタイプ:

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

引数:

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

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

戻り値:

  • string1 < string2 の場合は -1

  • string1 == string2 の場合は 0

  • string1 > string2 の場合は 1

C 言語での使用例:

int diff = weechat_utf8_charcmp ("aaa", "ccc");  /* == -2 */
スクリプト API ではこの関数を利用できません。

3.4.12. utf8_charcasecmp

WeeChat バージョン 1.0 で更新。

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

プロトタイプ:

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

引数:

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

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

戻り値:

  • string1 < string2 の場合は -1

  • string1 == string2 の場合は 0

  • string1 > string2 の場合は 1

C 言語での使用例:

int diff = weechat_utf8_charcasecmp ("aaa", "CCC");  /* == -2 */
スクリプト API ではこの関数を利用できません。

3.4.13. utf8_char_size_screen

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

プロトタイプ:

int weechat_utf8_char_size_screen (const char *string);

引数:

  • string: 文字列

戻り値:

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

C 言語での使用例:

int length_on_screen = weechat_utf8_char_size_screen ("é");  /* == 1 */
スクリプト API ではこの関数を利用できません。

3.4.14. 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 ではこの関数を利用できません。

3.4.15. 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 ではこの関数を利用できません。

3.4.16. 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 ではこの関数を利用できません。

3.4.17. 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 ではこの関数を利用できません。

3.5. Cryptography

Some cryptographic functions.

3.5.1. 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)

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.

戻り値:

  • 成功した場合は 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 ではこの関数を利用できません。

3.5.2. 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 ではこの関数を利用できません。

3.5.3. 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. ディレクトリ

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

3.6.1. 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_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)

3.6.2. 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)

3.6.3. 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)

3.6.4. 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 ではこの関数を利用できません。

3.6.5. 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 ではこの関数を利用できません。

3.6.6. 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 ではこの関数を利用できません。

3.7. ユーティリティ

便利な関数。

3.7.1. 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 ではこの関数を利用できません。

3.7.2. 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 ではこの関数を利用できません。

3.7.3. 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 ではこの関数を利用できません。

3.7.4. 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 ではこの関数を利用できません。

3.7.5. util_version_number

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

WeeChat バージョンの文字列を番号に変換。

プロトタイプ:

int 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 */
スクリプト API ではこの関数を利用できません。

3.8. ソート済みリスト

ソート済みリスト関数。

3.8.1. 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()

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

リストから要素を検索。

プロトタイプ:

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

3.8.4. 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")

3.8.5. 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")

3.8.6. 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")

3.8.7. 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)

3.8.8. 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")

3.8.9. 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)

3.8.10. 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)

3.8.11. 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))

3.8.12. 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: 0x%lx", weechat_list_user_data (item));
スクリプト API ではこの関数を利用できません。

3.8.13. 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))

3.8.14. 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)

3.8.15. 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)

3.8.16. 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. 配列リスト

配列リスト関数。

配列リストとはサイズ可変でソート可能なポインタのリストです。

3.9.1. 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 ではこの関数を利用できません。

3.9.2. 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 ではこの関数を利用できません。

3.9.3. 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 ではこの関数を利用できません。

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 ではこの関数を利用できません。

3.9.5. 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 ではこの関数を利用できません。

3.9.6. 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 ではこの関数を利用できません。

3.9.7. 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 ではこの関数を利用できません。

3.9.8. arraylist_clear

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

配列リストからすべての要素を削除します。

プロトタイプ:

int weechat_arraylist_clear (struct t_arraylist *arraylist);

引数:

  • arraylist: 配列リストポインタ

戻り値:

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

C 言語での使用例:

if (weechat_arraylist_clear (arraylist))
{
    /* 成功 */
}
スクリプト API ではこの関数を利用できません。

3.9.9. arraylist_free

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

配列リストを解放します。

プロトタイプ:

void weechat_arraylist_free (struct t_arraylist *arraylist);

引数:

  • arraylist: 配列リストポインタ

C 言語での使用例:

weechat_arraylist_free (arraylist);
スクリプト API ではこの関数を利用できません。

3.10. ハッシュテーブル

ハッシュテーブル関数。

3.10.1. hashtable_new

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

新しいハッシュテーブルを作成。

プロトタイプ:

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

  • type_values: ハッシュテーブルの値の種類:

    • WEECHAT_HASHTABLE_INTEGER

    • WEECHAT_HASHTABLE_STRING

    • WEECHAT_HASHTABLE_POINTER

    • WEECHAT_HASHTABLE_BUFFER

    • WEECHAT_HASHTABLE_TIME

  • 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 番目のキー

    • 戻り値:

      • key1key2 より小さい場合は負

      • key1key2 と同じ場合はゼロ

      • key1key2 より大きい場合は正

戻り値:

  • 新しいハッシュテーブルへのポインタ、エラーが起きた場合は NULL

C 言語での使用例:

struct t_hashtable *hashtable = weechat_hashtable_new (8,
                                                       WEECHAT_HASHTABLE_STRING,
                                                       WEECHAT_HASHTABLE_STRING,
                                                       NULL,
                                                       NULL);
スクリプト API ではこの関数を利用できません。

3.10.2. 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 ではこの関数を利用できません。

3.10.3. 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 ではこの関数を利用できません。

3.10.4. 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 ではこの関数を利用できません。

3.10.5. 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 ではこの関数を利用できません。

3.10.6. 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 ではこの関数を利用できません。

3.10.7. 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 コールバックを呼び出した際のコールバックの結果保存先へのポインタ

コールバックに渡される文字列 keyvalue は一時的な文字列で、コールバックの呼び出しが終了したら削除されます。

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 ではこの関数を利用できません。

3.10.8. 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 ではこの関数を利用できません。

3.10.9. 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 ではこの関数を利用できません。

3.10.10. 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: 時間

    • type_values: 値の型:

      • integer: 整数

      • string: 文字列

      • pointer: ポインタ

      • buffer: バッファ

      • time: 時間

    • 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 ではこの関数を利用できません。

3.10.11. 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 ではこの関数を利用できません。

3.10.12. 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 ではこの関数を利用できません。

3.10.13. 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 ではこの関数を利用できません。

3.10.14. hashtable_remove_all

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

ハッシュテーブルからすべての要素を削除。

プロトタイプ:

void weechat_hashtable_remove_all (struct t_hashtable *hashtable);

引数:

  • hashtable: ハッシュテーブルへのポインタ

C 言語での使用例:

weechat_hashtable_remove_all (hashtable);
スクリプト API ではこの関数を利用できません。

3.10.15. hashtable_free

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

ハッシュテーブルを開放。

プロトタイプ:

void weechat_hashtable_free (struct t_hashtable *hashtable);

引数:

  • hashtable: ハッシュテーブルへのポインタ

C 言語での使用例:

weechat_hashtable_free (hashtable);
スクリプト API ではこの関数を利用できません。

3.11. 設定ファイル

設定ファイルに関する関数。

3.11.1. config_new

WeeChat バージョン 1.5 で更新。

新しい設定ファイルを作成。

プロトタイプ:

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: 設定ファイルの名前 (パスと拡張子は不要)

  • 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 を使って) オプションを追加した後だけです。

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, config_file):
    # ...
    return weechat.WEECHAT_RC_OK

config_file = weechat.config_new("test", "my_config_reload_cb", "")

3.11.2. 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_READ_OK

      • WEECHAT_CONFIG_READ_MEMORY_ERROR

      • WEECHAT_CONFIG_READ_FILE_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_READ_OK;
    /* return WEECHAT_CONFIG_READ_MEMORY_ERROR; */
    /* return WEECHAT_CONFIG_READ_FILE_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 can not 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_create_option: str, callback_create_option_data: str,
                       callback_delete_option: str, callback_delete_option_data: str) -> str: ...

# 例
def my_section_read_cb(data, config_file, section, option_name, value):
    # ...
    return weechat.WEECHAT_CONFIG_OPTION_SET_OK_CHANGED
    # return weechat.WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE
    # return weechat.WEECHAT_CONFIG_OPTION_SET_OPTION_NOT_FOUND
    # return weechat.WEECHAT_CONFIG_OPTION_SET_ERROR

def my_section_write_cb(data, config_file, section_name):
    # ...
    return weechat.WEECHAT_CONFIG_WRITE_OK

def my_section_write_default_cb(data, config_file, section_name):
    # ...
    return weechat.WEECHAT_CONFIG_WRITE_OK

def my_section_create_option_cb(data, config_file, section, option_name, value):
    # ...
    return weechat.WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE

def my_section_delete_option_cb(data, config_file, section, option):
    # ...
    return weechat.WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED

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

3.11.3. 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")

3.11.4. config_new_option

WeeChat バージョン 1.5 で更新。

設定ファイルのあるセクションに新しいオプションを作成。

プロトタイプ:

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: 色

  • description: オプションの説明

  • string_values: 文字列で値を受ける (| で区切る)、integer 型の場合に使う (任意)

  • 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 *option1 =
    weechat_config_new_option (config_file, section, "option1", "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 *option2 =
    weechat_config_new_option (config_file, section, "option2", "integer",
                               "My option, type integer",
                               NULL,
                               0, 100,
                               "15",
                               "15",
                               0,
                               NULL, NULL, NULL,
                               NULL, NULL, NULL,
                               NULL, NULL, NULL);

/* integer (with string values) */
struct t_config_option *option3 =
    weechat_config_new_option (config_file, section, "option3", "integer",
                               "My option, type integer (with string values)",
                               "top|bottom|left|right",
                               0, 0,
                               "bottom",
                               "bottom",
                               0,
                               NULL, NULL, NULL,
                               NULL, NULL, NULL,
                               NULL, NULL, NULL);

/* string */
struct t_config_option *option4 =
    weechat_config_new_option (config_file, section, "option4", "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 *option5 =
    weechat_config_new_option (config_file, section, "option5", "color",
                               "My option, type color",
                               NULL,
                               0, 0,
                               "lightblue",
                               "lightblue",
                               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: str, value: str, 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 option4_check_value_cb(data, option, value):
    # ...
    return 1
    # return 0

def option4_change_cb(data, option):
    # ...

def option4_delete_cb(data, option):
    # ...

option1 = weechat.config_new_option(config_file, section, "option1", "boolean",
    "My option, type boolean",
    "", 0, 0, "on", "on", 0,
    "", "",
    "", "",
    "", "")

option2 = weechat.config_new_option(config_file, section, "option2", "integer",
    "My option, type integer",
    "", 0, 100, "15", "15", 0,
    "", "",
    "", "",
    "", "")

option3 = weechat.config_new_option(config_file, section, "option3", "integer",
    "My option, type integer (with string values)",
    "top|bottom|left|right",
    0, 0, "bottom", "bottom", 0,
    "", "",
    "", "",
    "", "")

option4 = weechat.config_new_option(config_file, section, "option4", "string",
    "My option, type string",
    "", 0, 0, "test", "test", 1,
    "option4_check_value_cb", "",
    "option4_change_cb", "",
    "option4_delete_cb", "")

option5 = weechat.config_new_option(config_file, section, "option5", "color",
    "My option, type color",
    "", 0, 0, "lightblue", "lightblue", 0,
    "", "",
    "", "",
    "", "")
Ruby では、3 組のコールバックとデータ (6 つの文字列変数) を渡す際に必ず 6 つの文字列変数の配列を 1 つ渡してください (これは Ruby が関数に 15 個以上の引数を渡せないことが原因です)、より詳しい内容は WeeChat スクリプト作成ガイドを参照してください (WeeChat バージョン 0.4.1 で修正済み)

3.11.5. 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")

3.11.6. 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 ではこの関数を利用できません。

3.11.7. 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 ではこの関数を利用できません。

3.11.8. 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):
    # ...

3.11.9. 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:
    # ...

3.11.10. config_option_set

オプションに新しい値を設定。

プロトタイプ:

int weechat_config_option_set (struct t_config_option *option,
                               const char *value, int run_callback);

引数:

  • option: オプションへのポインタ

  • value: オプションの新しい値、オプションのタイプによって以下の特殊値を取ることも可能です:

    • ブール型:

      • toggle: 現在の値を切り替える

    • 整数型 または :

      • ++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:
    # ...

3.11.11. 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:
    # ...

3.11.12. 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:
    # ...

3.11.13. 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")

3.11.14. 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

    • description: オプションの説明

戻り値:

  • プロパティの文字列値

C 言語での使用例:

const char *type = weechat_config_option_get_string (option, "type");
スクリプト API ではこの関数を利用できません。

3.11.15. 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 ではこの関数を利用できません。

3.11.16. 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):
    # ...

3.11.17. 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):
    # ...

3.11.18. config_boolean

オプションのブール値を返す。

プロトタイプ:

int weechat_config_boolean (struct t_config_option *option);

引数:

  • option: オプションへのポインタ

戻り値、オプションの型に依存:

  • boolean: オプションのブール値 (0 または 1)

  • integer: 0

  • string: 0

  • color: 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):
    # ...

3.11.19. config_boolean_default

オプションのデフォルトブール値を返す。

プロトタイプ:

int weechat_config_boolean_default (struct t_config_option *option);

引数:

  • option: オプションへのポインタ

戻り値、オプションの型に依存:

  • boolean: オプションのデフォルトブール値 (0 または 1)

  • integer: 0

  • string: 0

  • color: 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):
    # ...

3.11.20. config_integer

オプションの整数値を返す。

プロトタイプ:

int weechat_config_integer (struct t_config_option *option);

引数:

  • option: オプションへのポインタ

戻り値、オプションの型に依存:

  • boolean: オプションのブール値 (0 または 1)

  • integer: オプションの整数値

  • string: 0

  • color: 色インデックス

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)

3.11.21. config_integer_default

オプションのデフォルト整数値を返す。

プロトタイプ:

int weechat_config_integer_default (struct t_config_option *option);

引数:

  • option: オプションへのポインタ

戻り値、オプションの型に依存:

  • boolean: オプションのデフォルトブール値 (0 または 1)

  • integer: オプションのデフォルト整数値

  • string: 0

  • color: デフォルト色インデックス

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)

3.11.22. config_string

オプションの文字列値を返す。

プロトタイプ:

const char *weechat_config_string (struct t_config_option *option);

引数:

  • option: オプションへのポインタ

戻り値、オプションの型に依存:

  • boolean: 値が真の場合は "on"、それ以外の場合は "off"

  • integer: 値が文字列に対応付けられている場合はその文字列値、それ以外の場合は NULL

  • string: オプションの文字列値

  • color: 色名

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)

3.11.23. config_string_default

オプションのデフォルト文字列値を返す。

プロトタイプ:

const char *weechat_config_string_default (struct t_config_option *option);

引数:

  • option: オプションへのポインタ

戻り値、オプションの型に依存:

  • boolean: デフォルト値が真の場合は "on"、それ以外の場合は "off"

  • integer: デフォルト値が文字列に対応付けられている場合はその文字列値、それ以外の場合は NULL

  • string: オプションのデフォルト文字列値

  • color: デフォルト色名

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)

3.11.24. config_color

オプションの色値を返す。

プロトタイプ:

const char *weechat_config_color (struct t_config_option *option);

引数:

  • option: オプションへのポインタ

戻り値、オプションの型に依存:

  • boolean: NULL

  • integer: NULL

  • string: NULL

  • color: 色名

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")
value = weechat.config_color(option)

3.11.25. config_color_default

オプションのデフォルト色値を返す。

プロトタイプ:

const char *weechat_config_color_default (struct t_config_option *option);

引数:

  • option: オプションへのポインタ

戻り値、オプションの型に依存:

  • boolean: NULL

  • integer: NULL

  • string: NULL

  • color: デフォルト色名

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")
value = weechat.config_color_default(option)

3.11.26. 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, config_file, section_name):
    weechat.config_write_line(config_file, "my_section", "")
    weechat.config_write_option(config_file, option)
    return weechat.WEECHAT_RC_OK

3.11.27. 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, config_file, section_name):
    weechat.config_write_line(config_file, "my_section", "")
    weechat.config_write_line(config_file, "option", "value")
    return weechat.WEECHAT_RC_OK

3.11.28. 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:
    # ...

3.11.29. 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:
    # ...

3.11.30. 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:
    # ...

3.11.31. 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)

3.11.32. 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)

3.11.33. 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)

3.11.34. 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)

3.11.35. 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")

3.11.36. 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")

3.11.37. 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
    # ...

3.11.38. 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:
    # ...

3.11.39. 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")

3.11.40. 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. キー割り当て

キー割り当てに関する関数。

3.12.1. 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)

3.12.2. 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. 表示

バッファにテキストを表示する関数。

3.13.1. 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"))

3.13.2. 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 以上で利用可)

    • 任意で属性や背景色を指定した色 (以下を参照)

    • 属性:

      • 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" (任意)。以下の属性を使えます:

  • * : 太字

  • ! : 色反転

  • / : イタリック

  • _ : 下線

  • | : 属性を保存: 色を変更する際に太字/色反転/イタリック/下線の状態をリセットしない (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")))

3.13.3. printf

バッファにメッセージを表示。

プロトタイプ:

void weechat_printf (struct t_gui_buffer *buffer, const char *message, ...);

この関数は printf_date_tags 関数の別名です。以下に示す通り、どちらの関数も同じ結果を返します:

weechat_printf (buffer, "message");
weechat_printf_date_tags (buffer, 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") と書きます。

3.13.4. printf_date_tags

日付とタグを指定してバッファにメッセージを表示。

プロトタイプ:

void weechat_printf_date_tags (struct t_gui_buffer *buffer, time_t date,
                               const char *tags, const char *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: str, 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") と書きます。

3.13.5. printf_y

自由内容のバッファのある行にメッセージを表示

プロトタイプ:

void weechat_printf_y (struct t_gui_buffer *buffer, int y,
                       const char *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") と書きます。

3.13.6. 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" は引数の名前です (優先度は自動的に文字列から削除され、フックの名前になります)。

デフォルトの優先度は 1000 です。

C 言語での使用例:

/* hook modifier with priority = 2000 */
weechat_hook_modifier ("2000|input_text_display", &modifier_cb, NULL, NULL);

以下のフック型に対して優先度を設定できます: command、command_run、signal、hsignal、config、completion、modifier、info、info_hashtable、infolist、hdata、focus。

3.14.1. 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: コマンド名 (優先度の設定が可能、フックの優先度に関する注意を参照)

  • 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 引数: listadddel

  • 第 2 引数、第 1 引数に依存:

    • list: 第 2 引数なし

    • add: フィルタ名

    • del: フィルタ名および -all

デフォルトの補完候補コードは:

プラグイン 名前 説明

alias

alias

別名のリスト

alias

alias_value

別名の値

exec

exec_commands_ids

実行されたコマンドの識別子 (番号と名前)

fset

fset_options

設定ファイル、セクション、オプションの名前、オプションの値

guile

guile_script

スクリプトのリスト

irc

irc_channel

現在の IRC チャンネル

irc

irc_channel_nicks_hosts

現在の IRC チャンネルにいるニックネームとホスト名

irc

irc_channel_topic

現在の IRC チャンネルのトピック

irc

irc_channels

全ての IRC サーバのチャンネル

irc

irc_ignores_numbers

無視エントリの数

irc

irc_modelist_masks

現在の IRC チャンネルのモードリストマスク; 必須の引数: modelist mode

irc

irc_modelist_numbers

現在の IRC チャンネルのモードリスト番号; 必須の引数: modelist mode

irc

irc_msg_kick

デフォルトのキックメッセージ

irc

irc_msg_part

IRC チャンネルのデフォルト退出メッセージ

irc

irc_notify_nicks

通知エントリのニックネーム

irc

irc_privates

全ての IRC サーバにあるプライベートチャンネル

irc

irc_raw_filters

filters for irc raw buffer

irc

irc_server

現在の IRC サーバ

irc

irc_server_channels

現在の IRC サーバにあるチャンネル名

irc

irc_server_nick

現在の IRC サーバに接続中のニックネーム

irc

irc_server_nicks

現在の IRC サーバの全てのチャンネルにいるニックネーム

irc

irc_server_privates

現在の IRC サーバにあるプライベートチャンネル

irc

irc_servers

IRC サーバ (内部名)

irc

nick

現在の IRC チャンネルにいるニックネーム

javascript

javascript_script

スクリプトのリスト

lua

lua_script

スクリプトのリスト

perl

perl_script

スクリプトのリスト

php

php_script

スクリプトのリスト

python

python_script

スクリプトのリスト

relay

relay_free_port

リレープラグイン用の最初の空きポート番号

relay

relay_protocol_name

リレープラグインで利用可能な全ての protocol.name

relay

relay_relays

リレープラグインにおける現在のリレーの protocol.name

ruby

ruby_script

スクリプトのリスト

script

script_extensions

スクリプトの拡張子のリスト

script

script_files

スクリプトディレクトリ内のファイル

script

script_languages

スクリプトのプログラミング言語のリスト

script

script_scripts

リポジトリに存在するスクリプトのリスト

script

script_scripts_installed

インストール済みスクリプトのリスト (リポジトリから)

script

script_tags

リポジトリに存在するスクリプトに対するタグのリスト

spell

spell_dicts

インストール済み辞書のリスト

spell

spell_langs

サポートされる全ての言語のリスト

tcl

tcl_script

スクリプトのリスト

trigger

trigger_hook_arguments

フックに対するデフォルト引数

trigger

trigger_hook_command

フックに対するデフォルトコマンド

trigger

trigger_hook_conditions

バーのデフォルト状態

trigger

trigger_hook_rc

フックコールバックに対するデフォルトのリターンコード

trigger

trigger_hook_regex

フックに対するデフォルトの正規表現

trigger

trigger_hooks

トリガに対するフック

trigger

trigger_hooks_filter

トリガに対するフック (モニタバッファのフィルタ用)

trigger

trigger_names

トリガ

trigger

trigger_names_default

デフォルトトリガ

trigger

trigger_option_value

トリガオプションの値

trigger

trigger_options

トリガに対するオプション

trigger

trigger_post_action

トリガ実行後の処遇

weechat

bars_names

バーの名前

weechat

bars_options

バーのオプション

weechat

buffer_local_variable_value

value of a buffer local variable

weechat

buffer_local_variables

buffer local variables

weechat

buffer_properties_get

バッファから読み取り可能なプロパティ

weechat

buffer_properties_set

バッファに指定可能なプロパティ

weechat

buffers_names

バッファの名前

weechat

buffers_numbers

バッファの数

weechat

buffers_plugins_names

バッファの名前 (プラグインの名前を含めた)

weechat

colors

色名

weechat

commands

コマンド (WeeChat およびプラグイン); オプション引数: コマンドの前に追加するプレフィックス

weechat

config_files

設定ファイル

weechat

config_option_values

設定オプションの値

weechat

config_options

設定オプション

weechat

cursor_areas

カーソルを自由に動かせるエリア ("chat" またはバーの名前)

weechat

env_value

環境変数の値

weechat

env_vars

環境変数

weechat

filename

filename; optional argument: default path (evaluated, see /help eval)

weechat

filters_names

フィルタ名

weechat

infolists

フックされたインフォリストの名前

weechat

infos

フックされた情報の名前

weechat

keys_codes

キーコード

weechat

keys_codes_for_reset

リセットできるキーコード (追加、再定義、削除されたキー)

weechat

keys_contexts

キーコンテキスト

weechat

layouts_names

レイアウトの名前

weechat

nicks

現在のバッファのニックネームリストに含まれるニックネーム

weechat

palette_colors

パレット色

weechat

plugins_commands

プラグインが定義するマンド; オプション引数: コマンドの前に追加するプレフィックス

weechat

plugins_installed

インストールされたプラグインの名前

weechat

plugins_names

プラグイン名

weechat

proxies_names

プロキシの名前

weechat

proxies_options

プロキシのオプション

weechat

secured_data

保護データの名前 (sec.conf ファイル、セクションデータ)

weechat

weechat_commands

WeeChat コマンド; オプション引数: コマンドの前に追加するプレフィックス

weechat

windows_numbers

ウィンドウの数

xfer

nick

DCC チャットのニックネーム

特殊コード:

  • %%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 のように実行された場合、argvargv_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, buffer, args):
    # ...
    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", "")

3.14.2. 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) も使えます) (優先度の設定が可能、フックの優先度に関する注意を参照)

  • 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, completion_item, buffer, completion):
    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", "")

3.14.3. 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.

3.14.4. hook_completion_list_add

Deprecated since WeeChat 2.9 (still there for compatibility).
This function has been replaced by completion_list_add.

3.14.5. 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: フックするコマンド (ワイルドカード * を使うことができます) (優先度の設定が可能、フックの優先度に関する注意を参照)

  • 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, buffer, command):
    weechat.prnt("", "I'm eating the completion!")
    return weechat.WEECHAT_RC_OK_EAT

hook = weechat.hook_command_run("/input complete*", "my_command_run_cb", "")

3.14.6. 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, remaining_calls):
    # ...
    return weechat.WEECHAT_RC_OK

# timer called each 20 seconds
hook = weechat.hook_timer(20 * 1000, 0, 0, "my_timer_cb", "")

3.14.7. 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, fd):
    # ...
    return weechat.WEECHAT_RC_OK

sock = ...
hook = weechat.hook_fd(sock, 1, 0, 0, "my_fd_cb", "")

3.14.8. 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: データは利用可能だが子プロセスは終了していない

        • WEECHAT_HOOK_PROCESS_ERROR: コマンドの起動中にエラー

        • WEECHAT_HOOK_PROCESS_CHILD: 子プロセスからコールバックが呼び出された

    • 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 コールバックに送られます (関数の戻り値は外部コマンドを実行した場合の出力と同様に取り扱われます)。

WeeChat に関する情報 (例えば現在の安定版、最新の git コミット、…​) が欲しい場合、https://weechat.org/dev/info に書かれている URL を使ってください
コールバックにデータを送信するバッファのサイズは 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, command, return_code, out, err):
    if return_code == weechat.WEECHAT_HOOK_PROCESS_ERROR:
        weechat.prnt("", "Error with command '%s'" % command)
        return weechat.WEECHAT_RC_OK
    if return_code >= 0:
        weechat.prnt("", "return_code = %d" % return_code)
    if out:
        weechat.prnt("", "stdout: %s" % out)
    if err:
        weechat.prnt("", "stderr: %s" % err)
    return weechat.WEECHAT_RC_OK

hook = weechat.hook_process("ls", 5000, "my_process_cb", "")

# スクリプト関数を実行する例
def get_status(data):
    # 何かブロックを生じさせるようなことを実行...
    # ...
    return "this is the result"

def my_process_cb(data, command, return_code, out, err):
    if return_code == weechat.WEECHAT_HOOK_PROCESS_ERROR:
        weechat.prnt("", "Error with command '%s'" % command)
        return weechat.WEECHAT_RC_OK
    if return_code >= 0:
        weechat.prnt("", "return_code = %d" % return_code)
    if out:
        weechat.prnt("", "stdout: %s" % out)
    if err:
        weechat.prnt("", "stderr: %s" % err)
    return weechat.WEECHAT_RC_OK

hook = weechat.hook_process("func:get_status", 5000, "my_process_cb", "")

3.14.9. 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 にリダイレクトする

"url:…​" 型のコマンドでは、以下のコマンドを使うことができます (それぞれのオプションについては man curl_easy_setopt を参照):

オプション タイプ (1) 定数 (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

protocols

mask

http, https, ftp, ftps, scp, sftp, telnet, ldap, ldaps, dict, file, tftp, all, imap, imaps, pop3, pop3s, smtp, smtps, rtsp, rtmp, rtmpt, rtmpe, rtmpte, rtmps, rtmpts, gopher, smb, smbs

redir_protocols

mask

http, https, ftp, ftps, scp, sftp, telnet, ldap, ldaps, dict, file, tftp, all, imap, imaps, pop3, pop3s, smtp, smtps, rtsp, rtmp, rtmpt, rtmpe, rtmpte, rtmps, rtmpts, gopher, smb, smbs

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

netrc

long

ignored, optional, required

userpwd

string

proxyuserpwd

string

httpauth

mask

none, basic, digest, ntlm, any, anysafe, digest_ie, only, ntlm_wb, negotiate, gssapi, bearer

proxyauth

mask

none, basic, digest, ntlm, any, anysafe, digest_ie, only, ntlm_wb, negotiate, gssapi, bearer

netrc_file

string

username

string

password

string

proxyusername

string

proxypassword

string

tlsauth_type

mask

none, srp

tlsauth_username

string

tlsauth_password

string

sasl_ir

long

xoauth2_bearer

string

login_options

string

disallow_username_in_url

long

autoreferer

long

followlocation

long

put

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

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

mail_from

string

mail_rcpt

list

mail_auth

string

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

ftp_response_timeout

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