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

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

この文書の最新版を見るには以下のページを確認して下さい: http://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 と通信する際に使う構造体や型が定義されています。

2.1. マクロ

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

WEECHAT_PLUGIN_NAME("name"): プラグイン名
WEECHAT_PLUGIN_DESCRIPTION("description"): プラグインの短い説明
WEECHAT_PLUGIN_VERSION("1.0"): プラグインのバージョン番号
WEECHAT_PLUGIN_LICENSE("GPL3"): プラグインのライセンス

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 プラグイン構造体へのポインタ
argc: プラグインに対する引数の数 (ユーザがコマンドラインで指定)
argv: プラグインに対する引数

戻り値:

WEECHAT_RC_OK 成功した場合 (プラグインを読み込みます)
WEECHAT_RC_ERROR エラーが起きた場合 (プラグインを読み込みません)

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 libtoto.so toto.o

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

libtoto.so ファイルをシステムのプラグインディレクトリ (例えば /usr/local/lib/weechat/plugins) またはユーザのプラグインディレクトリ (例えば /home/xxx/.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 (void *data, struct t_gui_buffer *buffer, int argc,
                   char **argv, char **argv_eol)
{
    /* C 言語コンパイラ向けに必要 */
    (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);

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

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

3.1.1. weechat_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) での使用例:

# プロトタイプ
name = weechat.plugin_get_name(plugin)

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

3.2. 文字列

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

3.2.1. weechat_charset_set

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

プロトタイプ:

void weechat_charset_set (const char *charset);

引数:

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

C 言語での使用例:

weechat_charset_set ("iso-8859-1");

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

# プロトタイプ
weechat.charset_set(charset)

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

3.2.2. weechat_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) での使用例:

# プロトタイプ
str = weechat.iconv_to_internal(charset, string)

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

3.2.3. weechat_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) での使用例:

# プロトタイプ
str = weechat.iconv_from_internal(charset, string)

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

3.2.4. weechat_gettext

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

プロトタイプ:

const char *weechat_gettext (const char *string);

引数:

string: 翻訳元の文字列

戻り値:

翻訳済み文字列

C 言語での使用例:

char *str = weechat_gettext ("hello");

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

# プロトタイプ
str = weechat.gettext(string)

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

3.2.5. weechat_ngettext

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

プロトタイプ:

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

引数:

string: 翻訳元の文字列、単数形
plural: 翻訳元の文字列、複数形
count: 単数形と複数形のどちらを返すかの判断に使います (選択は設定言語に依存)

戻り値:

翻訳済みの文字列

C 言語での使用例:

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

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

# プロトタイプ
str = weechat.ngettext(string, plural, count)

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

3.2.6. weechat_strndup

複製した文字列を最大で length 文字分返す。

プロトタイプ:

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

引数:

string: 複製元の文字列
length: 複製する文字列の最大文字数

戻り値:

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

C 言語での使用例:

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

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

3.2.7. weechat_string_tolower

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

プロトタイプ:

void weechat_string_tolower (char *string);

引数:

string: 変換元の文字列

C 言語での使用例:

char str[] = "AbCdé";
weechat_string_tolower (str);  /* str is now: "abcdé" */

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

3.2.8. weechat_string_toupper

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

プロトタイプ:

void weechat_string_toupper (char *string);

引数:

string: 変換元の文字列

C 言語での使用例:

char str[] = "AbCdé";
weechat_string_toupper (str);  /* str is now: "ABCDé" */

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

3.2.9. weechat_strcasecmp

バージョン 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 */

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

3.2.10. weechat_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-Z" を "a-z" のように変換して比較
- 29: "A-Z [ \ ]" を "a-z { | }" のように変換して比較
- 30: "A-Z [ \ ] ^" を "a-z { | } ~" のように変換して比較

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

戻り値:

string1 < string2 の場合は -1
string1 == string2 の場合は 0
string1 > string2 の場合は 1

C 言語での使用例:

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

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

3.2.11. weechat_strncasecmp

バージョン 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 */

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

3.2.12. weechat_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-Z" を "a-z" のように変換して比較
- 29: "A-Z [ \ ]" を "a-z { | }" のように変換して比較
- 30: "A-Z [ \ ] ^" を "a-z { | } ~" のように変換して比較

Note	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 */

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

3.2.13. weechat_strcmp_ignore_chars

バージョン 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 */

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

3.2.14. weechat_strcasestr

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

プロトタイプ:

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

引数:

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

戻り値:

見つかった文字列へのポインタ、見つからない場合は NULL

C 言語での使用例:

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

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

3.2.15. weechat_strlen_screen

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

UTF-8 文字列をスクリーン上に表示するために必要なスクリーン幅を返す。非表示文字を 1 文字として数えます (これが weechat_utf8_strlen_screen 関数との違いです)。

プロトタイプ:

int weechat_strlen_screen (const char *string);

引数:

string: 文字列

戻り値:

UTF-8 文字列をスクリーン上に表示するために必要なスクリーン幅

C 言語での使用例:

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

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

# プロトタイプ
length = weechat.strlen_screen(string)

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

3.2.16. weechat_string_match

バージョン 1.0 で更新。

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

プロトタイプ:

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

引数:

string: 文字列
mask: ワイルドカード ("*") を含むマスク、各ワイルドカードは文字列中の 0 個またはそれ以上の文字にマッチします
case_sensitive: 大文字小文字を区別する場合は 1、区別しない場合は 0

Note	バージョン 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) での使用例:

# プロトタイプ
match = weechat.string_match(string, mask, case_sensitive)

# 例s
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.2.17. weechat_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/xxx/file.txt" */
/* ... */
free (str);

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

3.2.18. weechat_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);

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

3.2.19. weechat_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);

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

3.2.20. weechat_string_convert_escaped_chars

WeeChat バージョン 1.0 以�