path: root/doc/ja/weechat_plugin_api.ja.asciidoc

= WeeChat プラグイン API リファレンス
:author: Sébastien Helleu
:email: flashcode@flashtux.org
:toc2:
:toclevels: 4
:toc-title: 目次
:max-width: 100%


翻訳者:

* Ryuunosuke Ayanokouzi <i38w7i3@yahoo.co.jp>, 2014


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

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


[[introduction]]
== はじめに

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

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

[[plugins_in_weechat]]
== WeeChat プラグイン

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

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

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

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

[[macros]]
=== マクロ

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

WEECHAT_PLUGIN_NAME("name")::
    プラグイン名

WEECHAT_PLUGIN_DESCRIPTION("description")::
    プラグインの短い説明

WEECHAT_PLUGIN_VERSION("1.0")::
    プラグインのバージョン番号

WEECHAT_PLUGIN_LICENSE("GPL3")::
    プラグインのライセンス

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

[[main_functions]]
=== 重要な関数

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

* weechat_plugin_init
* weechat_plugin_end

==== weechat_plugin_init

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

プロトタイプ:

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

引数:

* 'plugin': WeeChat プラグイン構造体へのポインタ
* 'argc': プラグインに対する引数の数 (ユーザがコマンドラインで指定)
* 'argv': プラグインに対する引数

戻り値:

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

[[plugin_priority]]
===== プラグインの優先度

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

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

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

include::autogen/plugin_api/plugins_priority.asciidoc[]

==== weechat_plugin_end

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

プロトタイプ:

[source,C]
----
int weechat_plugin_end (struct t_weechat_plugin *plugin);
----

引数:

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

戻り値:

* 'WEECHAT_RC_OK' 成功した場合
* 'WEECHAT_RC_ERROR' エラーが起きた場合

[[compile_plugin]]
=== プラグインのコンパイル

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

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

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

[[load_plugin]]
=== プラグインを読み込む

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

WeeChat の中で:

----
/plugin load toto
----

[[plugin_example]]
=== プラグインの例

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

[source,C]
----
#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;
}
----

[[plugin_api]]
== プラグイン API

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

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

* 関数の説明、
* C 言語のプロトタイプ、
* 引数の詳細、
* 戻り値、
* C 言語での使用例、
* Python スクリプトでの使用例 (他のスクリプト言語を使う場合も文法は似ています)。

[[plugins]]
=== プラグイン

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

==== plugin_get_name

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

プロトタイプ:

[source,C]
----
const char *weechat_plugin_get_name (struct t_weechat_plugin *plugin);
----

引数:

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

戻り値:

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

C 言語での使用例:

[source,C]
----
const char *name = weechat_plugin_get_name (plugin);
----

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

[source,python]
----
# プロトタイプ
name = weechat.plugin_get_name(plugin)

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

[[strings]]
=== 文字列

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

==== charset_set

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

プロトタイプ:

[source,C]
----
void weechat_charset_set (const char *charset);
----

引数:

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

C 言語での使用例:

[source,C]
----
weechat_charset_set ("iso-8859-1");
----

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

[source,python]
----
# プロトタイプ
weechat.charset_set(charset)

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

==== iconv_to_internal

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

プロトタイプ:

[source,C]
----
char *weechat_iconv_to_internal (const char *charset, const char *string);
----

引数:

* 'charset': 変換元の文字列の文字セット
* 'string': 変換元の文字列

戻り値:

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

C 言語での使用例:

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

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

[source,python]
----
# プロトタイプ
str = weechat.iconv_to_internal(charset, string)

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

==== iconv_from_internal

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

プロトタイプ:

[source,C]
----
char *weechat_iconv_from_internal (const char *charset, const char *string);
----

引数:

* 'charset': 変換先の文字列の文字セット
* 'string': 変換元の文字列

戻り値:

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

C 言語での使用例:

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

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

[source,python]
----
# プロトタイプ
str = weechat.iconv_from_internal(charset, string)

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

==== gettext

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

プロトタイプ:

[source,C]
----
const char *weechat_gettext (const char *string);
----

引数:

* 'string': 翻訳元の文字列

戻り値:

* 翻訳済み文字列

C 言語での使用例:

[source,C]
----
char *str = weechat_gettext ("hello");
----

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

[source,python]
----
# プロトタイプ
str = weechat.gettext(string)

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

==== ngettext

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

プロトタイプ:

[source,C]
----
const char *weechat_ngettext (const char *string, const char *plural,
                              int count);
----

引数:

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

戻り値:

* 翻訳済みの文字列

C 言語での使用例:

[source,C]
----
char *str = weechat_ngettext ("file", "files", num_files);
----

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

[source,python]
----
# プロトタイプ
str = weechat.ngettext(string, plural, count)

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

==== strndup

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

プロトタイプ:

[source,C]
----
char *weechat_strndup (const char *string, int length);
----

引数:

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

戻り値:

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

C 言語での使用例:

[source,C]
----
char *str = weechat_strndup ("abcdef", 3);  /* result: "abc" */
/* ... */
free (str);
----

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

==== string_tolower

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

プロトタイプ:

[source,C]
----
void weechat_string_tolower (char *string);
----

引数:

* 'string': 変換元の文字列

C 言語での使用例:

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

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

==== string_toupper

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

プロトタイプ:

[source,C]
----
void weechat_string_toupper (char *string);
----

引数:

* 'string': 変換元の文字列

C 言語での使用例:

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

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

==== strcasecmp

_バージョン 1.0 で更新。_

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

プロトタイプ:

[source,C]
----
int weechat_strcasecmp (const char *string1, const char *string2);
----

引数:

* 'string1': 1 番目の比較対象の文字列
* 'string2': 2 番目の比較対象の文字列

戻り値:

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

C 言語での使用例:

[source,C]
----
int diff = weechat_strcasecmp ("aaa", "CCC");  /* == -2 */
----

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

==== strcasecmp_range

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

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

プロトタイプ:

[source,C]
----
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 言語での使用例:

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

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

==== strncasecmp

_バージョン 1.0 で更新。_

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

プロトタイプ:

[source,C]
----
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 言語での使用例:

[source,C]
----
int diff = weechat_strncasecmp ("aabb", "aacc", 2);  /* == 0 */
----

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

==== strncasecmp_range

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

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

プロトタイプ:

[source,C]
----
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 言語での使用例:

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

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

==== strcmp_ignore_chars

_バージョン 1.0 で更新。_

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

プロトタイプ:

[source,C]
----
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 言語での使用例:

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

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

==== strcasestr

_バージョン 1.3 で更新。_

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

プロトタイプ:

[source,C]
----
const char *weechat_strcasestr (const char *string, const char *search);
----

引数:

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

戻り値:

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

C 言語での使用例:

[source,C]
----
const char *pos = weechat_strcasestr ("aBcDeF", "de");  /* result: pointer to "DeF" */
----

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

==== strlen_screen

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

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

プロトタイプ:

[source,C]
----
int weechat_strlen_screen (const char *string);
----

引数:

* 'string': 文字列

戻り値:

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

C 言語での使用例:

[source,C]
----
int length_on_screen = weechat_strlen_screen ("é");  /* == 1 */
----

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

[source,python]
----
# プロトタイプ
length = weechat.strlen_screen(string)

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

==== string_match

_バージョン 1.0 で更新。_

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

プロトタイプ:

[source,C]
----
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 言語での使用例:

[source,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) での使用例:

[source,python]
----
# プロトタイプ
match = weechat.string_match(string, mask, case_sensitive)

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

==== string_expand_home

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

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

プロトタイプ:

[source,C]
----
char *weechat_string_expand_home (const char *path);
----

引数:

* 'path': パス

戻り値:

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

C 言語での使用例:

[source,C]
----
char *str = weechat_string_expand_home ("~/file.txt");
/* result: "/home/xxx/file.txt" */
/* ... */
free (str);
----

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

==== string_eval_path_home

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

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

. 先頭の `%h` を WeeChat ホームディレクトリで置換し、
. 先頭の `~` をユーザのホームディレクトリで置換し
  (<<_string_expand_home,weechat_string_expand_home>> を実行し)、
. 変数を評価します
  (<<_string_eval_expression,weechat_string_eval_expression>> を参照してください)。

プロトタイプ:

[source,C]
----
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,weechat_string_eval_expression>>
* 'extra_vars': 関数に渡されるハッシュテーブル
  <<_string_eval_expression,weechat_string_eval_expression>>
* 'options': 関数に渡されるハッシュテーブル
  <<_string_eval_expression,weechat_string_eval_expression>>

戻り値:

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

C 言語での使用例:

[source,C]
----
char *str = weechat_string_expand_home ("%h/test");
/* result: "/home/xxx/.weechat/test" */
/* ... */
free (str);
----

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

[source,python]
----
# プロトタイプ
path = weechat.string_eval_path_home(path, pointers, extra_vars, options)

# 例
path = weechat.string_eval_path_home("%h/test", "", "", "")
# path == "/home/xxx/.weechat/test"
----

==== string_remove_quotes

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

プロトタイプ:

[source,C]
----
char *weechat_string_remove_quotes (const char *string, const char *quotes);
----

引数:

* 'string': 文字列
* 'quotes': 引用符号のリストを含む文字列

戻り値:

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

C 言語での使用例:

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

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

==== string_strip

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

プロトタイプ:

[source,C]
----
char *weechat_string_strip (const char *string, int left, int right,
                            const char *chars);
----

引数:

* 'string': 文字列
* 'left': 0 以外の場合は左側の文字を削除
* 'right': 0 以外の場合は右側の文字を削除
* 'chars': 削除する文字を含む文字列

戻り値:

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

C 言語での使用例:

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

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

==== string_convert_escaped_chars

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

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

* `\"`: 二重引用符
* `\\`: バックスラッシュ
* `\a`: アラート (BEL)
* `\b`: バックスペース
* `\e`: エスケープ
* `\f`: 改ページ
* `\n`: 改行
* `\r`: キャリッジリターン
* `\t`: 水平タブ
* `\v`: 垂直タブ
* `\0ooo`: 文字の 8 進数表現 (ooo は 0 桁から 3 桁)
* `\xhh`: 文字の 16 進数表現 (hh は 1 桁から 2 桁)
* `\uhhhh`: ユニコード文字の 16 進数表現 (hhhh は 1 桁から 4 桁)
* `\Uhhhhhhhh`: ユニコード文字の 16 進数表現 (hhhhhhhh は 1 桁から 8 桁)

プロトタイプ:

[source,C]
----
char *weechat_string_convert_escaped_chars (const char *string);
----

引数:

* 'string': 文字列

戻り値:

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

C 言語での使用例:

[source,C]
----
char *str = weechat_string_convert_escaped_chars ("snowman: \\u2603");
/* str == "snowman: ☃" */
/* ... */
free (str);
----

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

==== string_mask_to_regex

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

プロトタイプ:

[source,C]
----
char *weechat_string_mask_to_regex (const char *mask);
----

引数:

* 'mask': マスク

戻り値:

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

C 言語での使用例:

[source,C]
----
char *str_regex = weechat_string_mask_to_regex ("test*mask");
/* result: "test.*mask" */
/* ... */
free (str_regex);
----

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

[source,python]
----
# プロトタイプ
regex = weechat.string_mask_to_regex(mask)

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

==== string_regex_flags

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

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

プロトタイプ:

[source,C]
----
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 言語での使用例:

[source,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 */
----

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

==== string_regcomp

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

文字列の最初に含まれるオプションフラグを使って POSIX
拡張正規表現をコンパイル (フラグのフォーマットについては
<<_string_regex_flags,weechat_string_regex_flags>> を参照)。

プロトタイプ:

[source,C]
----
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` を参照)

C 言語での使用例:

[source,C]
----
regex_t my_regex;
if (weechat_string_regcomp (&my_regex, "(?i)test", REG_EXTENDED) != 0)
{
    /* error */
}
----

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

==== string_has_highlight

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

プロトタイプ:

[source,C]
----
int weechat_string_has_highlight (const char *string,
                                  const char highlight_words);
----

引数:

* 'string': 文字列、
* 'highlight_words': ハイライトしたい単語のリスト、コンマ区切り

戻り値:

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

C 言語での使用例:

[source,C]
----
int hl = weechat_string_has_highlight ("my test string", "test,word2");  /* == 1 */
----

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

[source,python]
----
# プロトタイプ
highlight = weechat.string_has_highlight(string, highlight_words)

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

==== string_has_highlight_regex

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

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

プロトタイプ:

[source,C]
----
int weechat_string_has_highlight_regex (const char *string, const char *regex);
----

引数:

* 'string': 文字列
* 'regex': POSIX 拡張正規表現

戻り値:

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

C 言語での使用例:

[source,C]
----
int hl = weechat_string_has_highlight_regex ("my test string", "test|word2");  /* == 1 */
----

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

[source,python]
----
# プロトタイプ
highlight = weechat.string_has_highlight_regex(string, regex)

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

==== string_replace

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

プロトタイプ:

[source,C]
----
char *weechat_string_replace (const char *string, const char *search,
                              const char *replace);
----

引数:

* 'string': 文字列
* 'search': マッチさせる文字列
* 'replace': 'search' を置き換える文字列

戻り値:

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

C 言語での使用例:

[source,C]
----
char *str = weechat_string_replace ("test", "s", "x");  /* result: "text" */
/* ... */
free (str);
----

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

==== string_replace_regex

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

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

プロトタイプ:

[source,C]
----
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,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': コールバックを呼び出す際にコールバックに渡すポインタ

戻り値:

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

C 言語での使用例:

[source,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);
}
----

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

==== string_split

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

プロトタイプ:

[source,C]
----
char **weechat_string_split (const char *string, const char *separators,
                             int keep_eol, int num_items_max,
                             int *num_items);
----

引数:

* 'string': 分割する文字列
* 'separators': 分割に使う区切り文字
* 'keep_eol':
** 0: 区切り文字ごとの文字列に分割
** 1: 文字列の最初から区切り文字までの文字列に分割 (下の例を参照)
** 2: 1 と同じだが、文字列の最後から区切り文字を削除しない
   _(WeeChat バージョン 0.3.6 以上で利用可)_
* 'num_items_max': 分割回数の上限 (0 = 制限なし)
* 'num_items': 分割回数を返す整数型変数へのポインタ

戻り値:

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

C 言語での使用例:

[source,C]
----
char **argv;
int argc;
argv = weechat_string_split ("abc de  fghi", " ", 0, 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", " ", 1, 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);
----

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

==== string_split_shell

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

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

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

プロトタイプ:

[source,C]
----
char **weechat_string_split_shell (const char *string, int *num_items);
----

引数:

* 'string': 分割する文字列
* 'num_items': 分割回数を返す整数型変数へのポインタ

戻り値:

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

C 言語での使用例:

[source,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);
----

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

==== string_free_split

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

プロトタイプ:

[source,C]
----
void weechat_string_free_split (char **split_string);
----

引数:

* 'split_string': 関数 <<_string_split,weechat_string_split>>
  が返した分割文字列の配列

C 言語での使用例:

[source,C]
----
char *argv;
int argc;
argv = weechat_string_split (string, " ", 0, 0, &argc);
/* ... */
weechat_string_free_split (argv);
----

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

==== string_build_with_split_string

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

プロトタイプ:

[source,C]
----
char *weechat_string_build_with_split_string (char **split_string,
                                              const char *separator);
----

引数:

* 'split_string': 関数 <<_string_split,weechat_string_split>>
  が返した分割文字列の配列
* 'separator': 文字列を分割する区切り文字

戻り値:

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

C 言語での使用例:

[source,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);
----

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

==== string_split_command

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

プロトタイプ:

[source,C]
----
char **weechat_string_split_command (const char *command, char separator);
----

引数:

* 'command': 分割するコマンド
* 'separator': 区切り文字

戻り値:

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

C 言語での使用例:

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

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

==== string_free_split_command

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

プロトタイプ:

[source,C]
----
void weechat_string_free_split_command (char **split_command);
----

引数:

* 'split_command': 関数 <<_string_split_command,weechat_string_split_command>>
  が返す分割コマンドの配列

C 言語での使用例:

[source,C]
----
char **argv = weechat_string_split_command ("/command1 arg;/command2", ';');
/* ... */
weechat_free_split_command (argv);
----

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

==== string_format_size

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

プロトタイプ:

[source,C]
----
char *weechat_string_format_size (unsigned long long size);
----

引数:

* 'size': サイズ (バイト単位)

戻り値:

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

C 言語での使用例:

[source,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);
----

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

==== string_remove_color

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

プロトタイプ:

[source,C]
----
char *weechat_string_remove_color (const char *string,
                                   const char *replacement);
----

引数:

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

戻り値:

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

C 言語での使用例:

[source,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) での使用例:

[source,python]
----
# プロトタイプ
str = weechat.string_remove_color(string, replacement)

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

==== string_encode_base64

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

文字列を base64 でエンコード。

プロトタイプ:

[source,C]
----
void weechat_string_encode_base64 (const char *from, int length, char *to);
----

引数:

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

C 言語での使用例:

[source,C]
----
char *string = "abcdefgh", result[128];
weechat_string_encode_base64 (string, strlen (string), result);
/* result == "YWJjZGVmZ2g=" */
----

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

==== string_decode_base64

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

base64 文字列をデコード。

プロトタイプ:

[source,C]
----
int weechat_string_decode_base64 (const char *from, char *to);
----

引数:

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

戻り値:

* *to に保存された文字列の長さ (最後の '\0' は数えません)

C 言語での使用例:

[source,C]
----
char *string = "YWJjZGVmZ2g=", result[128];
int length;
length = weechat_string_decode_base64 (string, result);
/* length == 8, result == "abcdefgh" */
----

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

==== string_is_command_char

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

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

プロトタイプ:

[source,C]
----
int weechat_string_is_command_char (const char *string);
----

引数:

* 'string': 文字列

戻り値:

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

C 言語での使用例:

[source,C]
----
int command_char1 = weechat_string_is_command_char ("/test");  /* == 1 */
int command_char2 = weechat_string_is_command_char ("test");   /* == 0 */
----

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

[source,python]
----
# プロトタイプ
is_cmdchar = weechat.string_is_command_char(string)

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

==== string_input_for_buffer

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

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

プロトタイプ:

[source,C]
----
const char *weechat_string_input_for_buffer (const char *string);
----

引数:

* 'string': 文字列

戻り値:

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

C 言語での使用例:

[source,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) での使用例:

[source,python]
----
# プロトタイプ
str = weechat.string_input_for_buffer(string)

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

==== string_eval_expression

_WeeChat バージョン 0.4.0 以上で利用可、バージョン 0.4.2、1.0、1.1、1.2、1.3 で更新。_

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

[NOTE]
バージョン 1.0 以降、入れ子変数を使えるようになりました、例:
`${color:${variable}}`。

プロトタイプ:

[source,C]
----
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,weechat_string_regcomp>>
   または regcomp (`man regcomp` を参照) でコンパイル済みの正規表現へのポインタ
   ('regex_t' 構造体); このオプションは (以下の) ハッシュテーブル構造体 'options'
   メンバの 'regex' とよく似ていますが、より高速に動作します
* 'extra_vars': 展開される追加変数 (NULL でも可)
* 'options': いくつかのオプションを含むハッシュテーブル (キーと値は必ず文字列)
  (NULL でも可):
** 'type':
   デフォルトの挙動では式中の変数をその値で置換するだけです、その他に以下のタイプを使うことができます:
*** 'condition': 条件式として式を評価します:
    演算子と括弧が使われます、結果はブール値 ("0" または "1") です
** 'prefix': 置換する変数のプレフィックス (デフォルト: "${")
** 'suffix': 置換する変数のサフィックス (デフォルト: "}")
** 'regex': 'expr' のテキストを置換する正規表現
   (この場合 'expr' は評価されません)
** 'regex_replace': 'regex' と一緒に使われる置換テキスト、'expr'
   に含まれるテキストを置換する ('regex_replace' は、'expr' 内で
   'regex' 引数にマッチする部分が見つからなくなるまで、毎回評価されます)

戻り値:

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

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

[width="100%",cols="2,8,4,4",options="header"]
|===
| フォーマット | 説明 | 例 | 結果

| `${name}` | 'extra_vars' の変数 `name` の値に展開 |
  `${name}` | `value`

| `${eval:xxx}` +
  (_WeeChat バージョン 1.3 以上で利用可_) |
  評価する文字列 |
  `${eval:${date:${weechat.look.buffer_time_format}}}` |
 `19:02:45` (オプション weechat.look.buffer_time_format
 内に色コードが存在する場合色付き)

| `${esc:xxx}` +
  `${\xxx}` | エスケープ文字を含む文字列 |
  `${esc:prefix\tmessage}` +
  `${\ua9}` |
  `prefix<TAB>message` +
  `©`

| `${hide:x,value}` |
  隠す文字を含むテキスト (`value` に含まれる文字をすべて `x` で置換) |
  `${hide:*,password}` |
 `********`

| `${re:N}` |
  正規表現のキャプチャグループ: 0 = マッチするすべての文字列、1 から 99 =
  キャプチャされたグループ、`+` = 最後にキャプチャされたグループ |
  `${re:1}` |
  `test`

| `${color:name}` |
  WeeChat 色コード (色名部分はオプション属性をとることも可能です),
  フォーマットを確認するには関数 <<_color,weechat_color>> をご確認ください |
  `${color:red}red text` +
  `${color:*214}bold orange text` |
  `red text` (赤色で) +
  `bold orange text` (太字オレンジ色で)

| `${info:name}` +
  `${info:name,arguments}` |
  WeeChat またはプラグインのインフォ、<<_info_get,weechat_info_get>>
  を参照 |
  `${info:version}` +
  `${info:irc_nick_color_name,foo}` |
  `1.0` +
  `lightblue`

| `${date}` +
  `${date:xxx}` +
  (_WeeChat バージョン 1.3 以上で利用可_) |
  現在の日付/時刻、カスタムフォーマットを使うことも可能です (`man strftime` を参照)、
  デフォルトフォーマットは `%F %T` |
  `${date}` +
  `${date:%H:%M:%S}` |
  `2015-06-30 19:02:45` +
  `19:02:45`

| `${env:NAME}` +
  (_WeeChat バージョン 1.2 以上で利用可_) |
  Value of the environment variable `NAME` |
  `${env:HOME}` |
  `/home/user`

| `${sec.data.name}` |
  セキュアデータ `name` の値 |
  `${sec.data.freenode_pass}` |
  `my_password`

| `${file.section.option}` |
  オプションの値 |
  `${weechat.look.buffer_time_format}` |
  `%H:%M:%S`

| `${name}` |
  バッファに対するローカル変数 `name` の値 |
  `${nick}` |
  `FlashCode`

| `${hdata.var1.var2...}` +
  `${hdata[list].var1.var2...}` |
  hdata の値 (`window` と `buffer`
  ポインタはデフォルトで現在のウィンドウ/バッファに設定されます) |
  `${buffer[gui_buffers].full_name}` +
  `${window.buffer.number}` |
  `core.weechat` +
  `1`
|===

C 言語での使用例:

[source,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", "\\w+://\\S+");
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=)(\\S+)");
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) での使用例:

[source,python]
----
# プロトタイプ
str = weechat.string_eval_expression(expr, pointers, extra_vars, options)

# 例

# 条件式の評価
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": "\\w+://\\S+",
    "regex_replace": "[ ${re:0} ]",
}
str4 = weechat.string_eval_expression("test: https://weechat.org", {}, {}, options)  # "test: [ https://weechat.org ]"

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

[[utf-8]]
=== UTF-8

UTF-8 文字列関数。

==== utf8_has_8bits

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

プロトタイプ:

[source,C]
----
int weechat_utf8_has_8bits (const char *string);
----

引数:

* 'string': 文字列

戻り値:

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

C 言語での使用例:

[source,C]
----
if (weechat_utf8_has_8bits (string))
{
    /* ... */
}
----

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

==== utf8_is_valid

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

プロトタイプ:

[source,C]
----
int weechat_utf8_is_valid (const char *string, char **error);
----

引数:

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

戻り値:

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

C 言語での使用例:

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

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

==== utf8_normalize

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

プロトタイプ:

[source,C]
----
void weechat_utf8_normalize (char *string, char replacement);
----

引数:

* 'string': 文字列
* 'replacement': 非 UTF-8 文字を置き換える文字

C 言語での使用例:

[source,C]
----
weechat_utf8_normalize (string, '?');
----

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

==== utf8_prev_char

_バージョン 1.3 で更新。_

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

プロトタイプ:

[source,C]
----
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 言語での使用例:

[source,C]
----
const char *prev_char = weechat_utf8_prev_char (string, ptr_in_string);
----

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

==== utf8_next_char

_バージョン 1.3 で更新。_

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

プロトタイプ:

[source,C]
----
const char *weechat_utf8_next_char (const char *string);
----

引数:

* 'string': 文字列

戻り値:

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

C 言語での使用例:

[source,C]
----
const char *next_char = weechat_utf8_next_char (string);
----

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

==== utf8_char_int

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

プロトタイプ:

[source,C]
----
int weechat_utf8_char_int (const char *string);
----

引数:

* 'string': 文字列

戻り値:

* UTF-8 文字の整数表現

C 言語での使用例:

[source,C]
----
int char_int = weechat_utf8_char_int ("être");  /* "ê" as integer */
----

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

==== utf8_char_size

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

プロトタイプ:

[source,C]
----
int weechat_utf8_char_size (const char *string);
----

引数:

* 'string': 文字列

戻り値:

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

C 言語での使用例:

[source,C]
----
int char_size = weechat_utf8_char_size ("être");  /* == 2 */
----

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

==== utf8_strlen

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

プロトタイプ:

[source,C]
----
int weechat_utf8_strlen (const char *string);
----

引数:

* 'string': 文字列

戻り値:

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

C 言語での使用例:

[source,C]
----
int length = weechat_utf8_strlen ("chêne");  /* == 5 */
----

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

==== utf8_strnlen

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

プロトタイプ:

[source,C]
----
int weechat_utf8_strnlen (const char *string, int bytes);
----

引数:

* 'string': 文字列
* 'bytes': バイト数の上限

戻り値:

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

C 言語での使用例:

[source,C]
----
int length = weechat_utf8_strnlen ("chêne", 4);  /* == 3 */
----

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

==== utf8_strlen_screen

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

プロトタイプ:

[source,C]
----
int weechat_utf8_strlen_screen (const char *string);
----

引数:

* 'string': 文字列

戻り値:

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

C 言語での使用例:

[source,C]
----
int length_on_screen = weechat_utf8_strlen_screen ("é");  /* == 1 */
----

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

==== utf8_charcmp

_バージョン 1.0 で更新。_

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

プロトタイプ:

[source,C]
----
int weechat_utf8_charcmp (const char *string1, const char *string2);
----

引数:

* 'string1': 1 番目の比較文字列
* 'string2': 2 番目の比較文字列

戻り値:

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

C 言語での使用例:

[source,C]
----
int diff = weechat_utf8_charcmp ("aaa", "ccc");  /* == -2 */
----

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

==== utf8_charcasecmp

_バージョン 1.0 で更新。_

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

プロトタイプ:

[source,C]
----
int weechat_utf8_charcasecmp (const char *string1, const char *string2);
----

引数:

* 'string1': 1 番目の比較文字列
* 'string2': 2 番目の比較文字列

戻り値:

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

C 言語での使用例:

[source,C]
----
int diff = weechat_utf8_charcasecmp ("aaa", "CCC");  /* == -2 */
----

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

==== utf8_char_size_screen

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

プロトタイプ:

[source,C]
----
int weechat_utf8_char_size_screen (const char *string);
----

引数:

* 'string': 文字列

戻り値:

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

C 言語での使用例:

[source,C]
----
int length_on_screen = weechat_utf8_char_size_screen ("é");  /* == 1 */
----

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

==== utf8_add_offset

_バージョン 1.3 で更新。_

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

プロトタイプ:

[source,C]
----
const char *weechat_utf8_add_offset (const char *string, int offset);
----

引数:

* 'string': 文字列
* 'offset': 文字数

戻り値:

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

C 言語での使用例:

[source,C]
----
const char *str = "chêne";
const char *str2 = weechat_utf8_add_offset (str, 3);  /* points to "ne" */
----

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

==== utf8_real_pos

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

プロトタイプ:

[source,C]
----
int weechat_utf8_real_pos (const char *string, int pos);
----

引数:

* 'string': 文字列
* 'pos': 位置 (文字目)

戻り値:

* 真の位置 (バイト目)

C 言語での使用例:

[source,C]
----
int pos = weechat_utf8_real_pos ("chêne", 3);  /* == 4 */
----

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

==== utf8_pos

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

プロトタイプ:

[source,C]
----
int weechat_utf8_pos (const char *string, int real_pos);
----

引数:

* 'string': 文字列
* 'real_pos': 真の位置 (バイト目)

戻り値:

* 位置 (文字目)

C 言語での使用例:

[source,C]
----
int pos = weechat_utf8_pos ("chêne", 4);  /* == 3 */
----

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

==== utf8_strndup

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

プロトタイプ:

[source,C]
----
char *weechat_utf8_strndup (const char *string, int length);
----

引数:

* 'string': 文字列
* 'length': 複製する文字数の最大値

戻り値:

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

C 言語での使用例:

[source,C]
----
char *string = weechat_utf8_strndup ("chêne", 3);  /* returns "chê" */
/* ... */
free (string);
----

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

[[directories]]
=== ディレクトリ

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

==== mkdir_home

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

プロトタイプ:

[source,C]
----
int weechat_mkdir_home (char *directory, int mode);
----

引数:

* 'directory': 作成するディレクトリの名前
* 'mode': ディレクトリのモード

戻り値:

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

C 言語での使用例:

[source,C]
----
if (!weechat_mkdir_home ("temp", 0755))
{
    /* error */
}
----

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

[source,python]
----
# プロトタイプ
weechat.mkdir_home(directory, mode)

# 例
weechat.mkdir_home("temp", 0755)
----

==== mkdir

ディレクトリを作成。

プロトタイプ:

[source,C]
----
int weechat_mkdir (char *directory, int mode);
----

引数:

* 'directory': 作成するディレクトリの名前
* 'mode': ディレクトリのモード

戻り値:

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

C 言語での使用例:

[source,C]
----
if (!weechat_mkdir ("/tmp/mydir", 0755))
{
    /* error */
}
----

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

[source,python]
----
# プロトタイプ
weechat.mkdir(directory, mode)

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

==== mkdir_parents

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

プロトタイプ:

[source,C]
----
int weechat_mkdir_parents (char *directory, int mode);
----

引数:

* 'directory': 作成するディレクトリの名前
* 'mode': ディレクトリのモード

戻り値:

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

C 言語での使用例:

[source,C]
----
if (!weechat_mkdir_parents ("/tmp/my/dir", 0755))
{
    /* error */
}
----

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

[source,python]
----
# プロトタイプ
weechat.mkdir_parents(directory, mode)

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

==== exec_on_files

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

プロトタイプ:

[source,C]
----
void weechat_exec_on_files (const char *directory,
                            int hidden_files,
                            void *data,
                            void (*callback)(void *data,
                                             const char *filename));
----

引数:

* 'directory': ファイルを検索するディレクトリ
* 'hidden_files': 検索対象に隠しファイルを含める場合は 1、含めない場合は 0
* 'data': WeeChat がコールバックを呼び出す際にコールバックに渡すポインタ
* 'callback': 各ファイルに対して呼び出す関数、引数:
** 'void *data': ポインタ
** 'const char *filename': 見つかったファイルの名前

C 言語での使用例:

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

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

==== file_get_content

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

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

プロトタイプ:

[source,C]
----
char *weechat_file_get_content (const char *filename);
----

引数:

* 'filename': パスやファイル名

戻り値:

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

C 言語での使用例:

[source,C]
----
char *content;

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

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

[[util]]
=== ユーティリティ

便利な関数。

==== util_timeval_cmp

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

プロトタイプ:

[source,C]
----
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 言語での使用例:

[source,C]
----
if (weechat_util_timeval_cmp (&tv1, &tv2) > 0)
{
    /* tv1 > tv2 */
}
----

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

==== util_timeval_diff

_バージョン 1.1 で更新。_

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

プロトタイプ:

[source,C]
----
long long weechat_util_timeval_diff (struct timeval *tv1, struct timeval *tv2);
----

引数:

* 'tv1': 1 番目の "timeval" 構造体
* 'tv2': 2 番目の "timeval" 構造体

戻り値:

* マイクロ秒単位の差

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

C 言語での使用例:

[source,C]
----
long long diff = weechat_util_timeval_diff (&tv1, &tv2);
----

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

==== util_timeval_add

_バージョン 1.1 で更新。_

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

プロトタイプ:

[source,C]
----
void weechat_util_timeval_add (struct timeval *tv, long long interval);
----

引数:

* 'tv': timeval 構造体
* 'interval': 時間間隔 (マイクロ秒単位)

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

C 言語での使用例:

[source,C]
----
weechat_util_timeval_add (&tv, 2000000);  /* add 2 seconds */
----

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

==== util_get_time_string

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

日付/時刻を "strftime" で作った文字列として取得します。フォーマットは
'weechat.look.time_format' で定義されています。

プロトタイプ:

[source,C]
----
const char *weechat_util_get_time_string (const time_t *date);
----

引数:

* 'date': 日付へのポインタ

戻り値:

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

C 言語での使用例:

[source,C]
----
time_t date = time (NULL);
weechat_printf (NULL, "date: %s",
                weechat_util_get_time_string (&date));
----

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

==== util_version_number

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

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

プロトタイプ:

[source,C]
----
int weechat_util_version_number (const char *version);
----

引数:

* 'version': WeeChat バージョン文字列 (例: "0.3.9" や "0.3.9-dev")

C 言語での使用例:

[source,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 */
----

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

[[sorted_lists]]
=== ソート済みリスト

ソート済みリスト関数。

==== list_new

新しいリストを作成。

プロトタイプ:

[source,C]
----
struct t_weelist *weechat_list_new ();
----

戻り値:

* 新しいリストへのポインタ

C 言語での使用例:

[source,C]
----
struct t_weelist *list = weechat_list_new ();
----

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

[source,python]
----
# プロトタイプ
list = weechat.list_new()

# 例
list = weechat.list_new()
----

==== list_add

リストに要素を追加。

プロトタイプ:

[source,C]
----
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 言語での使用例:

[source,C]
----
struct t_weelist_item *my_item =
    weechat_list_add (list, "my data", WEECHAT_LIST_POS_SORT, NULL);
----

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

[source,python]
----
# プロトタイプ
item = weechat.list_add(list, data, where, user_data)

# 例
item = weechat.list_add(list, "my data", weechat.WEECHAT_LIST_POS_SORT, "")
----

==== list_search

リストから要素を検索。

プロトタイプ:

[source,C]
----
struct t_weelist_item *weechat_list_search (struct t_weelist *weelist,
                                            const char *data);
----

引数:

* 'weelist': リストへのポインタ
* 'data': リストから検索するデータ

戻り値:

* 見つかった要素へのポインタ、見つからなかった場合は NULL

C 言語での使用例:

[source,C]
----
struct t_weelist_item *item = weechat_list_search (list, "my data");
----

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

[source,python]
----
# プロトタイプ
item = weechat.list_search(list, data)

# 例
item = weechat.list_search(list, "my data")
----

==== list_search_pos

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

リストから要素の位置を検索。

プロトタイプ:

[source,C]
----
int weechat_list_search_pos (struct t_weelist *weelist,
                             const char *data);
----

引数:

* 'weelist': リストへのポインタ
* 'data': リストから検索するデータ

戻り値:

* 見つかった要素の位置、見つからなかった場合は -1

C 言語での使用例:

[source,C]
----
int pos_item = weechat_list_search_pos (list, "my data");
----

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

[source,python]
----
# プロトタイプ
pos_item = weechat.list_search_pos(list, data)

# 例
pos_item = weechat.list_search_pos(list, "my data")
----

==== list_casesearch

大文字小文字を無視してリストから要素を検索。

プロトタイプ:

[source,C]
----
struct t_weelist_item *weechat_list_casesearch (struct t_weelist *weelist,
                                                const char *data);
----

引数:

* 'weelist': リストへのポインタ
* 'data': リストから検索するデータ

戻り値:

* 見つかった要素へのポインタ、見つからなかった場合は NULL

C 言語での使用例:

[source,C]
----
struct t_weelist_item *item = weechat_list_casesearch (list, "my data");
----

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

[source,python]
----
# プロトタイプ
item = weechat.list_casesearch(list, data)

# 例
item = weechat.list_casesearch(list, "my data")
----

==== list_casesearch_pos

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

大文字小文字を無視してリストから要素の位置を検索。

プロトタイプ:

[source,C]
----
int weechat_list_casesearch_pos (struct t_weelist *weelist,
                                 const char *data);
----

引数:

* 'weelist': リストへのポインタ
* 'data': リストから検索するデータ

戻り値:

* 見つかった要素の位置、見つからなかった場合は -1

C 言語での使用例:

[source,C]
----
int pos_item = weechat_list_casesearch_pos (list, "my data");
----

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

[source,python]
----
# プロトタイプ
pos_item = weechat.list_casesearch_pos(list, data)

# 例
pos_item = weechat.list_casesearch_pos(list, "my data")
----

==== list_get

リスト中の位置を指定して要素を返す。

プロトタイプ:

[source,C]
----
struct t_weelist_item *weechat_list_get (struct t_weelist *weelist,
                                         int position);
----

引数:

* 'weelist': リストへのポインタ
* 'position': リスト中の位置 (1 番目の要素は 0)

戻り値:

* 見つかった要素へのポインタ、見つからなかった場合は NULL

C 言語での使用例:

[source,C]
----
struct t_weelist_item *item = weechat_list_get (list, 0);  /* first item */
----

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

[source,python]
----
# プロトタイプ
item = weechat.list_get(list, position)

# 例
item = weechat.list_get(list, 0)
----

==== list_set

ある要素に新しい値をセット。

プロトタイプ:

[source,C]
----
void weechat_list_set (struct t_weelist_item *item, const char *value);
----

引数:

* 'item': 要素へのポインタ
* 'value': 要素にセットする新しい値

C 言語での使用例:

[source,C]
----
weechat_list_set (item, "new data");
----

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

[source,python]
----
# プロトタイプ
weechat.list_set(item, value)

# 例
weechat.list_set(item, "new data")
----

==== list_next

リストから 1 つ後の要素を返す。

プロトタイプ:

[source,C]
----
struct t_weelist_item *weechat_list_next (struct t_weelist_item *item);
----

引数:

* 'item': 要素へのポインタ

戻り値:

* 1 つ後の要素へのポインタ、ポインタがリストの最後を指す場合は NULL

C 言語での使用例:

[source,C]
----
struct t_weelist_item *next_item = weechat_list_next (item);
----

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

[source,python]
----
# プロトタイプ
item = weechat.list_next(item)

# 例
item = weechat.list_next(item)
----

==== list_prev

リストから 1 つ前の要素を返す。

プロトタイプ:

[source,C]
----
struct t_weelist_item *weechat_list_prev (struct t_weelist_item *item);
----

引数:

* 'item': 要素へのポインタ

戻り値:

* 1 つ前の要素へのポインタ、ポインタがリストの最初を指す場合は NULL

C 言語での使用例:

[source,C]
----
struct t_weelist_item *prev_item = weechat_list_prev (item);
----

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

[source,python]
----
# プロトタイプ
item = weechat.list_prev(item)

# 例
item = weechat.list_prev(item)
----

==== list_string

ある要素の文字列値を返す。

プロトタイプ:

[source,C]
----
const char *weechat_list_string (struct t_weelist_item *item);
----

引数:

* 'item': 要素へのポインタ

戻り値:

* 要素の文字列値

C 言語での使用例:

[source,C]
----
weechat_printf (NULL, "value of item: %s", weechat_list_string (item));
----

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

[source,python]
----
# プロトタイプ
value = weechat.list_string(item)

# 例
weechat.prnt("", "value of item: %s" % weechat.list_string(item))
----

==== list_size

リストのサイズ (要素の個数) を返す。

プロトタイプ:

[source,C]
----
char *weechat_list_size (struct t_weelist *weelist);
----

引数:

* 'weelist': 要素へのポインタ

戻り値:

* リストのサイズ (要素の個数)、リストが空の場合は 0

C 言語での使用例:

[source,C]
----
weechat_printf (NULL, "size of list: %d", weechat_list_size (list));
----

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

[source,python]
----
# プロトタイプ
size = weechat.list_size(list)

# 例
weechat.prnt("", "size of list: %d" % weechat.list_size(list))
----

==== list_remove

ある要素をリストから削除。

プロトタイプ:

[source,C]
----
void weechat_list_remove (struct t_weelist *weelist,
                          struct t_weelist_item *item);
----

引数:

* 'weelist': リストへのポインタ
* 'item': 要素へのポインタ

C 言語での使用例:

[source,C]
----
weechat_list_remove (list, item);
----

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

[source,python]
----
# プロトタイプ
weechat.list_remove(list, item)

# 例
weechat.list_remove(list, item)
----

==== list_remove_all

あるリストの要素をすべて削除。

プロトタイプ:

[source,C]
----
void weechat_list_remove_all (struct t_weelist *weelist);
----

引数:

* 'weelist': リストへのポインタ

C 言語での使用例:

[source,C]
----
weechat_list_remove_all (list);
----

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

[source,python]
----
# プロトタイプ
weechat.list_remove_all(list)

# 例
weechat.list_remove_all(list)
----

==== list_free

リストを開放。

プロトタイプ:

[source,C]
----
void weechat_list_free (struct t_weelist *weelist);
----

引数:

* 'weelist': リストへのポインタ

C 言語での使用例:

[source,C]
----
weechat_list_free (list);
----

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

[source,python]
----
# プロトタイプ
weechat.list_free(list)

# 例
weechat.list_free(list)
----

[[hashtables]]
=== ハッシュテーブル

ハッシュテーブル関数。

==== hashtable_new

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

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

プロトタイプ:

[source,C]
----
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 番目のキー
** 戻り値:
*** 'key1' が 'key2' より小さい場合は負
*** 'key1' が 'key2' と同じ場合はゼロ
*** 'key1' が 'key2' より大きい場合は正

戻り値:

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

C 言語での使用例:

[source,C]
----
struct t_hashtable *hashtable = weechat_hashtable_new (8,
                                                       WEECHAT_HASHTABLE_STRING,
                                                       WEECHAT_HASHTABLE_STRING,
                                                       NULL,
                                                       NULL);
----

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

==== hashtable_set_with_size

_WeeChat バージョン 0.3.3 以上で利用可、バージョン 0.4.2 で更新。_

キーと値のサイズを使ってハッシュテーブルの要素を追加または更新。

プロトタイプ:

[source,C]
----
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 言語での使用例:

[source,C]
----
weechat_hashtable_set_with_size (hashtable, "my_key", 0,
                                 my_buffer, sizeof (my_buffer_struct));
----

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

==== hashtable_set

_WeeChat バージョン 0.3.3 以上で利用可、バージョン 0.4.2 で更新。_

ハッシュテーブルの要素を追加または更新。

プロトタイプ:

[source,C]
----
struct t_hashtable_item *weechat_hashtable_set (struct t_hashtable *hashtable,
                                                const void *key, const void *value);
----

引数:

* 'hashtable': ハッシュテーブルへのポインタ
* 'key': キーへのポインタ
* 'value': 値へのポインタ

戻り値:

* 作成または更新された要素へのポインタ、エラーが起きた場合は NULL

C 言語での使用例:

[source,C]
----
weechat_hashtable_set (hashtable, "my_key", "my_value");
----

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

==== hashtable_get

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

ハッシュテーブルからキーに紐付けられた値を取得。

プロトタイプ:

[source,C]
----
void *weechat_hashtable_get (struct t_hashtable *hashtable, void *key);
----

引数:

* 'hashtable': ハッシュテーブルへのポインタ
* 'key': キーへのポインタ

戻り値:

* キーに対応する値、キーが見つからない場合は NULL

C 言語での使用例:

[source,C]
----
void *value = weechat_hashtable_get (hashtable, "my_key");
----

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

==== hashtable_has_key

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

ハッシュテーブル内にキーが有るか確認する。

プロトタイプ:

[source,C]
----
int weechat_hashtable_has_key (struct t_hashtable *hashtable, void *key);
----

引数:

* 'hashtable': ハッシュテーブルへのポインタ
* 'key': キーへのポインタ

戻り値:

* ハッシュテーブル内にキーが有る場合は 1、無い場合は 0

C 言語での使用例:

[source,C]
----
if (weechat_hashtable_has_key (hashtable, "my_key"))
{
    /* key is in hashtable */
    /* ... */
}
----

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

==== hashtable_map

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

ハッシュテーブルのすべてのエントリに対して関数を呼び出す。

プロトタイプ:

[source,C]
----
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': コールバックを呼び出す際のコールバックの結果保存先へのポインタ

C 言語での使用例:

[source,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);
----

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

==== hashtable_map_string

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

ハッシュテーブルのすべてのエントリに対して関数を呼び出す、キーと値を文字列として関数に渡す。

プロトタイプ:

[source,C]
----
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': コールバックを呼び出した際のコールバックの結果保存先へのポインタ

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

C 言語での使用例:

[source,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);
----

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

==== hashtable_dup

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

ハッシュテーブルを複製。

プロトタイプ:

[source,C]
----
struct t_hashtable *weechat_hashtable_dup (struct t_hashtable *hashtable);
----

引数:

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

戻り値:

* 複製されたハッシュテーブ

C 言語での使用例:

[source,C]
----
struct t_hashtable *new_hashtable = weechat_hashtable_dup (hashtable);
----

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

==== hashtable_get_integer

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

ハッシュテーブルプロパティの整数値を返す。

プロトタイプ:

[source,C]
----
int weechat_hashtable_get_integer (struct t_hashtable *hashtable,
                                   void *property);
----

引数:

* 'hashtable': ハッシュテーブルへのポインタ
* 'property': プロパティ名:
** 'size': ハッシュテーブルの内部配列 "htable" のサイズ
** 'items_count': ハッシュテーブルに含まれる要素の数

戻り値:

* プロパティの整数値

C 言語での使用例:

[source,C]
----
int items_count = weechat_hashtable_get_integer (hashtable, "items_count");
----

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

==== hashtable_get_string

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

ハッシュテーブルプロパティを文字列値で返す。

プロトタイプ:

[source,C]
----
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 言語での使用例:

[source,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"));
----

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

==== hashtable_set_pointer

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

ハッシュテーブルのポインタ値を設定。

プロトタイプ:

[source,C]
----
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 言語での使用例:

[source,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);
----

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

==== hashtable_add_to_infolist

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

ハッシュテーブルの要素をインフォリスト要素に追加

プロトタイプ:

[source,C]
----
int weechat_hashtable_add_to_infolist (struct t_hashtable *hashtable,
                                       struct t_infolist_item *infolist_item,
                                       const char *prefix);
----

引数:

* 'hashtable': ハッシュテーブルへのポインタ
* 'infolist_item': infolist 要素へのポインタ
* 'prefix': infolist で名前のプレフィックスとして使う文字列

戻り値:

* 成功した場合は 1、エラーが起きた場合は 0

C 言語での使用例:

[source,C]
----
weechat_hashtable_add_to_infolist (hashtable, infolist_item, "testhash");

/* if hashtable contains:
     "key1" => "value 1"
     "key2" => "value 2"
   then following variables will be added to infolist item:
     "testhash_name_00000"  = "key1"
     "testhash_value_00000" = "value 1"
     "testhash_name_00001"  = "key2"
     "testhash_value_00001" = "value 2"
*/
----

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

==== hashtable_remove

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

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

プロトタイプ:

[source,C]
----
void weechat_hashtable_remove (struct t_hashtable *hashtable, const void *key);
----

引数:

* 'hashtable': ハッシュテーブルへのポインタ
* 'key': キーへのポインタ

C 言語での使用例:

[source,C]
----
weechat_hashtable_remove (hashtable, "my_key");
----

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

==== hashtable_remove_all

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

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

プロトタイプ:

[source,C]
----
void weechat_hashtable_remove_all (struct t_hashtable *hashtable);
----

引数:

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

C 言語での使用例:

[source,C]
----
weechat_hashtable_remove_all (hashtable);
----

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

==== hashtable_free

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

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

プロトタイプ:

[source,C]
----
void weechat_hashtable_free (struct t_hashtable *hashtable);
----

引数:

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

C 言語での使用例:

[source,C]
----
weechat_hashtable_free (hashtable);
----

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

[[configuration_files]]
=== 設定ファイル

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

==== config_new

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

プロトタイプ:

[source,C]
----
struct t_config_file *weechat_config_new (const char *name,
                                          int (*callback_reload)(void *data,
                                                                 struct t_config_file *config_file),
                                          void *callback_reload_data);
----

引数:

* 'name': 設定ファイルの名前 (パスと拡張子は不要)
* 'callback_reload': `/reload` で設定ファイルを再読み込みする際に呼び出す関数
  (任意、NULL でも可)、引数と戻り値:
** '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_data': WeeChat が reload
  コールバックを呼び出す際にコールバックに渡すポインタ

戻り値:

* 新しい設定ファイルへのポインタ、エラーが起きた場合は NULL

[NOTE]
この関数はディスク上にファイルを作りません。ファイルを作るには
<<_config_write,weechat_config_write>>
関数を使ってください。この関数を呼び出す必要があるのは
(<<_config_new_section,weechat_config_new_section>> を使って) セクションもしくは
(<<_config_new_option,weechat_config_new_option>> を使って) オプションを追加した後だけです。

C 言語での使用例:

[source,C]
----
int
my_config_reload_cb (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);
----

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

[source,python]
----
# プロトタイプ
config_file = weechat.config_new(name, calback_reload, callback_reload_data)

# 例
def my_config_reload_cb(data, config_file):
    # ...
    return weechat.WEECHAT_RC_OK

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

==== config_new_section

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

プロトタイプ:

[source,C]
----
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)(void *data,
                         struct t_config_file *config_file,
                         struct t_config_section *section,
                         const char *option_name,
                         const char *value),
    void *callback_read_data,
    int (*callback_write)(void *data,
                          struct t_config_file *config_file,
                          const char *section_name),
    void *callback_write_data,
    int (*callback_write_default)(void *data,
                                  struct t_config_file *config_file,
                                  const char *section_name);
    void *callback_write_default_data,
    int (*callback_create_option)(void *data,
                                  struct t_config_file *config_file,
                                  struct t_config_section *section,
                                  const char *option_name,
                                  const char *value),
    void *callback_create_option_data,
    int (*callback_delete_option)(void *data,
                                  struct t_config_file *config_file,
                                  struct t_config_section *section,
                                  struct t_config_option *option),
    void *callback_delete_option_data);
----

引数:

* 'config_file': 設定ファイルへのポインタ
* 'name': セクションの名前
* 'user_can_add_options':
  ユーザがこのセクションに新しいオプションを作成することを許可する場合は 1、禁止する場合は 0
* 'user_can_delete_options':
  ユーザがこのセクションからオプションを削除することを許可する場合は 1、禁止する場合は 0
* 'callback_read': このセクションに含まれるオプションがディスクから読まれた際に呼び出す関数
  (特別な関数を使ってセクションを読み出す必要がある場合を除いて、殆どの場合は
  NULL を指定する)、引数と戻り値:
** '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_data': WeeChat がコールバックを呼び出す際にコールバックに渡すポインタ
* 'callback_write': セクションをファイルに書き込む際に呼び出す関数
  (特別な関数を使ってセクションを書き込む必要がある場合を除いて、殆どの場合は
  NULL を指定する)、引数と戻り値:
** 'void *data': ポインタ
** 'struct t_config_file *config_file': 設定ファイルへのポインタ
** 'struct t_config_section *section': セクションへのポインタ
** 'const char *option_name': オプションの名前
** 戻り値:
*** 'WEECHAT_CONFIG_WRITE_OK'
*** 'WEECHAT_CONFIG_WRITE_ERROR'
*** 'WEECHAT_CONFIG_WRITE_MEMORY_ERROR'
* callback_write_data: WeeChat がコールバックを呼び出す際にコールバックに渡すポインタ
* callback_write_default:
  セクションのデフォルト値が必ずファイルに書き込まれる際に呼び出す関数、引数と戻り値:
** '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_data': WeeChat
  がコールバックを呼び出す際にコールバックに渡すポインタ
* 'callback_create_option': セクションに新しいオプションを作成する際に呼び出す関数
  (セクションに新しいオプションを作成することを禁止する場合は
  NULL)、引数と戻り値:
** '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_data': WeeChat
  がコールバックを呼び出す際にコールバックに渡すポインタ
* 'callback_delete_option': セクションからオプションを削除する際に呼び出す関数
  (セクションからオプションを削除することを禁止する場合は
  NULL)、引数と戻り値:
** '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_data': WeeChat
  がコールバックを呼び出す際にコールバックに渡すポインタ

戻り値:

* 設定ファイルの新しいセクションへのポインタ、エラーが起きた場合は NULL

C 言語での使用例:

[source,C]
----
int
my_section_read_cb (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_OPTION_NOT_FOUND; */
    /* return WEECHAT_CONFIG_OPTION_SET_ERROR; */
}

int
my_section_write_cb (void *data, struct t_config_file *config_file,
                     const char *section_name)
{
    /* ... */

    return WEECHAT_CONFIG_WRITE_OK;
    /* return WEECHAT_CONFIG_WRITE_ERROR; */
}

int
my_section_write_default_cb (void *data, struct t_config_file *config_file,
                             const char *section_name)
{
    /* ... */

    return WEECHAT_CONFIG_WRITE_OK;
    /* return WEECHAT_CONFIG_WRITE_ERROR; */
}

int
my_section_create_option_cb (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_SAME_VALUE;
    /* return WEECHAT_CONFIG_OPTION_SET_ERROR; */
}

int
my_section_delete_option_cb (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_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,  /* read callback */
                                NULL, NULL,  /* write callback */
                                NULL, NULL,  /* write default callback */
                                NULL, NULL,  /* create option callback */
                                NULL, NULL);  /* delete option callback */

/* 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,
                                &my_section_write_cb, NULL,
                                &my_section_write_default_cb, NULL,
                                &my_section_create_option_cb, NULL,
                                &my_section_delete_option_cb, NULL);
----

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

[source,python]
----
# プロトタイプ
section = weechat.config_new_section(config_file, name,
    user_can_add_options, user_can_delete_options,
    callback_read, callback_read_data,
    callback_write, callback_write_data,
    callback_create_option, callback_create_option_data,
    callback_delete_option, callback_delete_option_data)

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

==== config_search_section

設定ファイルからセクションを検索。

プロトタイプ:

[source,C]
----
struct t_config_section *weechat_config_search_section (
    struct t_config_file *config_file,
    const char *section_name);
----

引数:

* 'config_file': 設定ファイルへのポインタ
* 'section_name': 検索するセクションの名前

戻り値:

* セクションが見つかった場合はセクションへのポインタ、見つからなかった場合は NULL

C 言語での使用例:

[source,C]
----
struct t_config_section *section = weechat_config_search_section (config_file,
                                                                  "section");
----

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

[source,python]
----
# プロトタイプ
section = weechat.config_search_section(config_file, section_name)

# 例
section = weechat.config_search_section(config_file, "section")
----

==== config_new_option

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

プロトタイプ:

[source,C]
----
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)(void *data,
                                struct t_config_option *option,
                                const char *value),
    void *callback_check_value_data,
    void (*callback_change)(void *data,
                            struct t_config_option *option),
    void *callback_change_data,
    void (*callback_delete)(void *data,
                            struct t_config_option *option),
    void *callback_delete_data);
----

引数:

* 'config_file': 設定ファイルへのポインタ
* 'section': セクションへのポインタ
* 'name': オプションの名前
* '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': オプションの新しい値をチェックする際に呼び出す関数
  (任意)、引数と戻り値:
** 'void *data': ポインタ
** 'struct t_config_option *option': オプションへのポインタ
** 'const char *value': オプションの新しい値
** 戻り値:
*** 値が有効の場合は 1
*** 値が無効の場合は 0
* 'callback_check_value_data': WeeChat が check_value
  コールバックを呼び出す際にコールバックに渡すポインタ
* 'callback_change': オプションの値を変更した際に呼び出す関数
  (任意)、引数:
** 'void *data': ポインタ
** 'struct t_config_option *option': オプションへのポインタ
* 'callback_change_data': WeeChat が change
  コールバックを呼び出す際にコールバックに渡すポインタ
* 'callback_delete': オプションを削除する前に際に呼び出す関数
  (任意)、引数:
** 'void *data': ポインタ
** 'struct t_config_option *option': オプションへのポインタ
* 'callback_delete_data': WeeChat が delete
  コールバックを呼び出す際にコールバックに渡すポインタ

戻り値:

* セクションの新しいオプションへのポインタ、エラーが起きた場合は NULL

C 言語での使用例:

[source,C]
----
/* boolean */
struct t_config_option *option1 =
    weechat_config_new_option (config_file, section, "option1", "boolean",
                               "My option, type boolean"
                               NULL,  /* string values */
                               0, 0,  /* min, max */
                               "on",  /* default */
                               "on",  /* value */
                               0,  /* null value allowed */
                               NULL, NULL,  /* check callback */
                               NULL, NULL,  /* change callback */
                               NULL, NULL);  /* delete callback */

/* integer */
struct t_config_option *option2 =
    weechat_config_new_option (config_file, section, "option2", "integer",
                               "My option, type integer"
                               NULL,  /* string values */
                               0, 100,  /* min, max */
                               "15",  /* default */
                               "15",  /* value */
                               0,  /* null value allowed */
                               NULL, NULL,  /* check callback */
                               NULL, NULL,  /* change callback */
                               NULL, NULL);  /* delete callback */

/* 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",  /* string values */
                               0, 0,  /* min, max */
                               "bottom",  /* default */
                               "bottom",  /* value */
                               0,  /* null value allowed */
                               NULL, NULL,  /* check callback */
                               NULL, NULL,  /* change callback */
                               NULL, NULL);  /* delete callback */

/* string */
struct t_config_option *option4 =
    weechat_config_new_option (config_file, section, "option4", "string",
                               "My option, type string"
                               NULL,  /* string values */
                               0, 0,  /* min, max */
                               "test",  /* default */
                               "test",  /* value */
                               1,  /* null value allowed */
                               NULL, NULL,  /* check callback */
                               NULL, NULL,  /* change callback */
                               NULL, NULL);  /* delete callback */

/* color */
struct t_config_option *option5 =
    weechat_config_new_option (config_file, section, "option5", "color",
                               "My option, type color"
                               NULL,  /* string values */
                               0, 0,  /* min, max */
                               "lightblue",  /* default */
                               "lightblue",  /* value */
                               0,  /* null value allowed */
                               NULL, NULL,  /* check callback */
                               NULL, NULL,  /* change callback */
                               NULL, NULL);  /* delete callback */
----

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

[source,python]
----
# プロトタイプ
option = weechat.config_new_option(config_file, section, name, type, description,
    string_values, min, max, default_value, value, null_value_allowed,
    callback_check_value, callback_check_value_data,
    callback_change, callback_change_data,
    callback_delete, callback_delete_data)

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

[NOTE]
Ruby では、3 組のコールバックとデータ (合わせて 6 つの文字列) を渡すために必ず 6 つの文字列をからなる配列を
1 つ渡してください (これは Ruby が 関数に 15 個以上の引数を渡せないことが原因です)、より詳しい情報は
'WeeChat スクリプト作成ガイド' を参照してください _(バージョン 0.4.1 で修正済み)_ 。

==== config_search_option

設定ファイルのセクションからオプションを検索。

プロトタイプ:

[source,C]
----
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 言語での使用例:

[source,C]
----
struct t_config_option *option =
    weechat_config_search_option (config_file, section, "option");
----

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

[source,python]
----
# プロトタイプ
option = weechat.config_search_option(config_file, section, option_name)

# 例
option = weechat.config_search_option(config_file, section, "option")
----

==== config_search_section_option

設定ファイルまたはセクションからセクションやオプションを検索。

プロトタイプ:

[source,C]
----
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 言語での使用例:

[source,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 */
}
----

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

==== config_search_with_string

ファイル/セクション/オプションの情報をオプションを完全な名前で検索。

プロトタイプ:

[source,C]
----
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 言語での使用例:

[source,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 */
}
----

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

==== config_string_to_boolean

テキストがブール値としての "true" または "false" かをチェック。

プロトタイプ:

[source,C]
----
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 言語での使用例:

[source,C]
----
if (weechat_config_string_to_boolean (option_value))
{
    /* value is "true" */
}
else
{
    /* value is "false" */
}
----

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

[source,python]
----
# プロトタイプ
value = weechat.config_string_to_boolean(text)

# 例
if weechat.config_string_to_boolean(text):
    # ...
----

==== config_option_reset

オプションをデフォルト値にリセット。

プロトタイプ:

[source,C]
----
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 言語での使用例:

[source,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) での使用例:

[source,python]
----
# プロトタイプ
rc = weechat.config_option_reset(option, run_callback)

# 例
rc = weechat.config_option_reset(option, 1)
if rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_CHANGED:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_ERROR:
    # ...
----

==== config_option_set

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

プロトタイプ:

[source,C]
----
int weechat_config_option_set (struct t_config_option *option,
                               const char *value, int run_callback);
----

引数:

* 'option': オプションへのポインタ
* 'value': オプションの新しい値
* 'run_callback': オプションが変更された際に、change コールバックを呼び出す場合は
  1、呼び出さない場合は 0

戻り値:

* オプションの値が変更された場合は 'WEECHAT_CONFIG_OPTION_SET_OK_CHANGED'
* 値が変更されなかった場合は 'WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE'
* エラーが起きた場合は 'WEECHAT_CONFIG_OPTION_SET_ERROR'

C 言語での使用例:

[source,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) での使用例:

[source,python]
----
# プロトタイプ
rc = weechat.config_option_set(option, value, run_callback)

# 例
rc = weechat.config_option_set(option, "new_value", 1)
if rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_CHANGED:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_ERROR:
    # ...
----

==== config_option_set_null

あるオプションに null (未定義値) を設定する。

プロトタイプ:

[source,C]
----
int weechat_config_option_set_null (struct t_config_option *option,
                                    int run_callback);
----

引数:

* 'option': オプションへのポインタ
* 'run_callback': オプションが (null 以外の値に) 変更された際に、change
  コールバックを呼び出す場合は 1、呼び出さない場合は 0

[NOTE]
オプションに null を設定することが許可されている場合にのみ null を設定できます
(<<_config_new_option,weechat_config_new_option>> を参照)。

戻り値:

* オプション値が変更された場合は 'WEECHAT_CONFIG_OPTION_SET_OK_CHANGED'
* 値が変更されなかった場合は 'WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE'
* エラーが起きた場合は 'WEECHAT_CONFIG_OPTION_SET_ERROR'

C 言語での使用例:

[source,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) での使用例:

[source,python]
----
# プロトタイプ
rc = weechat.config_option_set_null(option, run_callback)

# 例
rc = weechat.config_option_set_null(option, 1)
if rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_CHANGED:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_ERROR:
    # ...
----

==== config_option_unset

オプションをアンセット/リセットする。

プロトタイプ:

[source,C]
----
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 言語での使用例:

[source,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) での使用例:

[source,python]
----
# プロトタイプ
rc = weechat.config_option_unset(option)

# 例
rc = weechat.config_option_unset(option)
if rc == weechat.WEECHAT_CONFIG_OPTION_UNSET_OK_NO_RESET:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_UNSET_OK_RESET:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_UNSET_ERROR:
    # ...
----

==== config_option_rename

オプションをリネーム。

プロトタイプ:

[source,C]
----
void weechat_config_option_rename (struct t_config_option *option,
                                   const char *new_name);
----

引数:

* 'option': オプションへのポインタ
* 'new_name': オプションの新しい名前

C 言語での使用例:

[source,C]
----
weechat_config_option_rename (option, "new_name");
----

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

[source,python]
----
# プロトタイプ
weechat.config_option_rename(option, new_name)

# 例
weechat.config_option_rename(option, "new_name")
----

==== config_option_get_pointer

あるオプションのプロパティへのポインタを返す。

プロトタイプ:

[source,C]
----
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 *')
** '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 言語での使用例:

[source,C]
----
char *description = weechat_config_option_get_pointer (option, "description");
----

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

==== config_option_is_null

オプションの値が "null" (未定義値) か否かを確認。

プロトタイプ:

[source,C]
----
int weechat_config_option_is_null (struct t_config_option *option);
----

引数:

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

戻り値:

* オプションの値が "null" の場合は 1
* オプションの値が "null" でない場合は 0

C 言語での使用例:

[source,C]
----
if (weechat_config_option_is_null (option))
{
    /* value is "null" */
}
else
{
    /* value is not "null" */
}
----

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

[source,python]
----
# プロトタイプ
is_null = weechat.config_option_is_null(option)

# 例
if weechat.config_option_is_null(option):
    # ...
----

==== config_option_default_is_null

あるオプションのデフォルト値が "null" (未定義値) か否かを確認。

プロトタイプ:

[source,C]
----
int weechat_config_option_default_is_null (struct t_config_option *option);
----

引数:

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

戻り値:

* オプションの値が "null" の場合は 1
* オプションの値が "null" でない場合は 0

C 言語での使用例:

[source,C]
----
if (weechat_config_option_default_is_null (option))
{
    /* default value is "null" */
}
else
{
    /* default value is not "null" */
}
----

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

[source,python]
----
# プロトタイプ
is_null = weechat.config_option_default_is_null(option)

# 例
if weechat.config_option_default_is_null(option):
    # ...
----

==== config_boolean

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

プロトタイプ:

[source,C]
----
int weechat_config_boolean (struct t_config_option *option);
----

引数:

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

戻り値:

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

C 言語での使用例:

[source,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) での使用例:

[source,python]
----
# プロトタイプ
value = weechat.config_boolean(option)

# 例
option = weechat.config_get("plugin.section.option")
if weechat.config_boolean(option):
    # ...
----

==== config_boolean_default

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

プロトタイプ:

[source,C]
----
int weechat_config_boolean_default (struct t_config_option *option);
----

引数:

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

戻り値:

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

C 言語での使用例:

[source,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) での使用例:

[source,python]
----
# プロトタイプ
value = weechat.config_boolean_default(option)

# 例
option = weechat.config_get("plugin.section.option")
if weechat.config_boolean_default(option):
    # ...
----

==== config_integer

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

プロトタイプ:

[source,C]
----
int weechat_config_integer (struct t_config_option *option);
----

引数:

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

戻り値:

* オプションの整数値

C 言語での使用例:

[source,C]
----
struct t_config_option *option = weechat_config_get ("plugin.section.option");
int value = weechat_config_integer (option);
----

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

[source,python]
----
# プロトタイプ
value = weechat.config_integer(option)

# 例
option = weechat.config_get("plugin.section.option")
value = weechat.config_integer(option)
----

==== config_integer_default

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

プロトタイプ:

[source,C]
----
int weechat_config_integer_default (struct t_config_option *option);
----

引数:

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

戻り値:

* オプションのデフォルト整数値

C 言語での使用例:

[source,C]
----
struct t_config_option *option = weechat_config_get ("plugin.section.option");
int value = weechat_config_integer_default (option);
----

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

[source,python]
----
# プロトタイプ
value = weechat.config_integer_default(option)

# 例
option = weechat.config_get("plugin.section.option")
value = weechat.config_integer_default(option)
----

==== config_string

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

プロトタイプ:

[source,C]
----
const char *weechat_config_string (struct t_config_option *option);
----

引数:

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

戻り値:

* オプションの文字列値

C 言語での使用例:

[source,C]
----
struct t_config_option *option = weechat_config_get ("plugin.section.option");
const char *value = weechat_config_string (option);
----

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

[source,python]
----
# プロトタイプ
value = weechat.config_string(option)

# 例
option = weechat.config_get("plugin.section.option")
value = weechat.config_string(option)
----

==== config_string_default

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

プロトタイプ:

[source,C]
----
const char *weechat_config_string_default (struct t_config_option *option);
----

引数:

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

戻り値:

* オプションのデフォルト文字列値

C 言語での使用例:

[source,C]
----
struct t_config_option *option = weechat_config_get ("plugin.section.option");
const char *value = weechat_config_string_default (option);
----

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

[source,python]
----
# プロトタイプ
value = weechat.config_string_default(option)

# 例
option = weechat.config_get("plugin.section.option")
value = weechat.config_string_default(option)
----

==== config_color

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

プロトタイプ:

[source,C]
----
const char *weechat_config_color (struct t_config_option *option);
----

引数:

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

戻り値:

* オプションの色値 (色の名前を収めた文字列)

C 言語での使用例:

[source,C]
----
struct t_config_option *option = weechat_config_get ("plugin.section.option");
const char *color = weechat_config_color (option);
----

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

[source,python]
----
# プロトタイプ
value = weechat.config_color(option)

# 例
option = weechat.config_get("plugin.section.option")
value = weechat.config_color(option)
----

==== config_color_default

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

プロトタイプ:

[source,C]
----
const char *weechat_config_color_default (struct t_config_option *option);
----

引数:

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

戻り値:

* オプションのデフォルト色値 (色の名前を収めた文字列)

C 言語での使用例:

[source,C]
----
struct t_config_option *option = weechat_config_get ("plugin.section.option");
const char *color = weechat_config_color_default (option);
----

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

[source,python]
----
# プロトタイプ
value = weechat.config_color_default(option)

# 例
option = weechat.config_get("plugin.section.option")
value = weechat.config_color_default(option)
----

==== config_write_option

設定ファイルにオプションとその値を収めた行を書き込む (この関数をセクションの
"write" および "write_default" コールバック以外で使わないでください)。

プロトタイプ:

[source,C]
----
void weechat_config_write_option (struct t_config_file *config_file,
                                  struct t_config_option *option);
----

引数:

* 'config_file': 設定ファイルへのポインタ
* 'option': オプションへのポインタ

C 言語での使用例:

[source,C]
----
int
my_section_write_cb (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) での使用例:

[source,python]
----
# プロトタイプ
weechat.config_write_option(config_file, option)

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

==== config_write_line

設定ファイルに行を書き込む  (この関数をセクションの
"write" および "write_default" コールバック以外で使わないでください)

プロトタイプ:

[source,C]
----
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 言語での使用例:

[source,C]
----
int
my_section_write_cb (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) での使用例:

[source,python]
----
# プロトタイプ
weechat.config_write_line(config_file, option_name, value)

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

==== config_write

設定ファイルをディスクに書き込む。

プロトタイプ:

[source,C]
----
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 言語での使用例:

[source,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) での使用例:

[source,python]
----
# プロトタイプ
rc = weechat.config_write(config_file)

# 例
rc = weechat.config_write(config_file)
if rc == weechat.WEECHAT_CONFIG_WRITE_OK:
    # ...
elif rc == weechat.WEECHAT_CONFIG_WRITE_MEMORY_ERROR:
    # ...
elif rc == weechat.WEECHAT_CONFIG_WRITE_ERROR:
    # ...
----

==== config_read

設定ファイルをディスクから読み込む。

プロトタイプ:

[source,C]
----
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 言語での使用例:

[source,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) での使用例:

[source,python]
----
# プロトタイプ
rc = weechat.config_read(config_file)

# 例
rc = weechat.config_read(config_file)
if rc == weechat.WEECHAT_CONFIG_READ_OK:
    # ...
elif rc == weechat.WEECHAT_CONFIG_READ_MEMORY_ERROR:
    # ...
elif rc == weechat.WEECHAT_CONFIG_READ_FILE_NOT_FOUND:
    # ...
----

==== config_reload

設定ファイルをディスクから再読み込みする。

プロトタイプ:

[source,C]
----
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 言語での使用例:

[source,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) での使用例:

[source,python]
----
# プロトタイプ
rc = weechat.config_reload(config_file)

# 例
rc = weechat.config_reload(config_file)
if rc == weechat.WEECHAT_CONFIG_READ_OK:
    # ...
elif rc == weechat.WEECHAT_CONFIG_READ_MEMORY_ERROR:
    # ...
elif rc == weechat.WEECHAT_CONFIG_READ_FILE_NOT_FOUND:
    # ...
----

==== config_option_free

オプションを開放。

プロトタイプ:

[source,C]
----
void weechat_config_option_free (struct t_config_option *option);
----

引数:

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

C 言語での使用例:

[source,C]
----
weechat_config_option_free (option);
----

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

[source,python]
----
# プロトタイプ
weechat.config_option_free(option)

# 例
weechat.config_option_free(option)
----

==== config_section_free_options

セクションの全てのオプションを開放。

プロトタイプ:

[source,C]
----
void weechat_config_section_free_options (struct t_config_section *section);
----

引数:

* 'section': セクションへのポインタ

C 言語での使用例:

[source,C]
----
weechat_config_section_free_options (section);
----

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

[source,python]
----
# プロトタイプ
weechat.config_section_free_options(section)

# 例
weechat.config_section_free_options(section)
----

==== config_section_free

セクションを開放。

プロトタイプ:

[source,C]
----
void weechat_config_section_free (struct t_config_section *section);
----

引数:

* 'section': セクションへのポインタ

C 言語での使用例:

[source,C]
----
weechat_config_section_free (section);
----

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

[source,python]
----
# プロトタイプ
weechat.config_section_free(section)

# 例
weechat.config_section_free(section)
----

==== config_free

設定ファイルを開放。

プロトタイプ:

[source,C]
----
void weechat_config_free (struct t_config_file *config_file);
----

引数:

* 'config_file': 設定ファイルへのポインタ

C 言語での使用例:

[source,C]
----
weechat_config_free (config_file);
----

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

[source,python]
----
# プロトタイプ
weechat.config_free(config_file)

# 例
weechat.config_free(config_file)
----

==== config_get

完全な名前でオプションを検索。

プロトタイプ:

[source,C]
----
struct t_config_option *weechat_config_get (const char *option_name);
----

引数:

* 'option_name': オプションの完全な名前 (フォーマット: "file.section.option")

戻り値:

* 見つかったオプションへのポインタ、見つからなかった場合は NULL

C 言語での使用例:

[source,C]
----
struct t_config_option *option = weechat_config_get ("weechat.look.item_time_format");
----

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

[source,python]
----
# プロトタイプ
option = weechat.config_get(option_name)

# 例
option = weechat.config_get("weechat.look.item_time_format")
----

==== config_get_plugin

プラグインの設定ファイル (plugins.conf) からオプションを検索。

プロトタイプ:

[source,C]
----
const char *weechat_config_get_plugin (const char *option_name);
----

引数:

* 'option_name': オプション名、プレフィックス "plugins.var.xxx."
  が自動的に付けられる (ここで "xxx" は現在のプラグイン名)。

戻り値:

* 見つかったオプションの値、オプションが見つからなければ NULL

C 言語での使用例:

[source,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) での使用例:

[source,python]
----
# プロトタイプ
value = weechat.config_get_plugin(option_name)

# 例
value = weechat.config_get_plugin("option")
----

==== config_is_set_plugin

オプションがプラグインの設定ファイル (plugins.conf) で設定されているか否かを確認。

プロトタイプ:

[source,C]
----
int weechat_config_is_set_plugin (const char *option_name);
----

引数:

* 'option_name': オプション名、プレフィックス "plugins.var.xxx."
  が自動的に付けられる (ここで "xxx" は現在のプラグイン名)。

戻り値:

* オプションが設定されている場合は 1、オプションが存在しない場合は 0

C 言語での使用例:

[source,C]
----
if (weechat_config_is_set_plugin ("option"))
{
    /* option is set */
}
else
{
    /* option does not exist */
}
----

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

[source,python]
----
# プロトタイプ
value = weechat.config_is_set_plugin(option_name)

# 例
if weechat.config_is_set_plugin("option"):
    # option is set
    # ...
else:
    # option does not exist
    # ...
----

==== config_set_plugin

プラグイン設定ファイル (plugins.conf) のオプションの新しい値を設定。

プロトタイプ:

[source,C]
----
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 言語での使用例:

[source,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) での使用例:

[source,python]
----
# プロトタイプ
rc = weechat.config_set_plugin(option_name, value)

# 例
rc = weechat.config_set_plugin("option", "test_value")
if rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_CHANGED:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_OK_SAME_VALUE:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_OPTION_NOT_FOUND:
    # ...
elif rc == weechat.WEECHAT_CONFIG_OPTION_SET_ERROR:
    # ...
----

==== config_set_desc_plugin

_WeeChat バージョン 0.3.5 以上で利用可。_

プラグイン設定ファイル (plugins.conf) のオプションに関する説明を設定。

プロトタイプ:

[source,C]
----
void weechat_config_set_desc_plugin (const char *option_name,
                                     const char *description);
----

引数:

* 'option_name': オプション名、プレフィックス "plugins.var.xxx."
  が自動的に付けられる (ここで "xxx" は現在のプラグイン名)。
* 'description': オプションの説明

[NOTE]
オプション (plugins.var.xxx.option_name)
が存在しなくても問題ありません。この説明を持つような名前のオプションが作成されます。

C 言語での使用例:

[source,C]
----
weechat_config_set_desc_plugin ("option", "description of option");
----

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

[source,python]
----
# プロトタイプ
weechat.config_set_desc_plugin(option_name, description)

# 例
version = weechat.info_get("version_number", "") or 0
if int(version) >= 0x00030500:
    weechat.config_set_desc_plugin("option", "description of option")
----

==== config_unset_plugin

プラグイン設定ファイル (plugins.conf) のオプションをアンセットする。

プロトタイプ:

[source,C]
----
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 言語での使用例:

[source,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) での使用例:

[source,python]
----
# プロトタイプ
rc = weechat.config_unset_plugin(option_name)

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

[[key_bindings]]
=== キー割り当て

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

==== key_bind

_WeeChat バージョン 0.3.6 以上で利用可。_

新しいキー割り当てを追加。

[NOTE]
コマンド `/key bind`
とは異なり、この関数がすでに存在しているキー割り当てを変更することはありません。新しいキー割り当てを作成するだけです。キー割り当てを削除するには
<<_key_unbind,weechat_key_unbind>> を使ってください。

プロトタイプ:

[source,C]
----
int weechat_key_bind (const char *context, struct t_hashtable *keys);
----

引数:

* 'context': キーのコンテキスト:
** 'default': デフォルトコンテキスト (一般的な動作)
** 'search': 検索コンテキスト (バッファ中のテキストを検索中)
** 'cursor': スクリーン上のカーソルを自由に移動
** 'mouse': マウスイベント用のキー
* 'keys': キー割り当てを収めたハッシュテーブル

戻り値:

* 追加されたキー割り当て

C 言語での使用例:

[source,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) での使用例:

[source,python]
----
# プロトタイプ
num_keys = weechat.key_bind(context, keys)

# 例
keys = {"@chat(python.test):button1": "hsignal:test_mouse",
        "@chat(python.test):wheelup": "/mycommand up",
        "@chat(python.test):wheeldown": "/mycommand down"}
weechat.key_bind("mouse", keys)
----

==== key_unbind

_WeeChat バージョン 0.3.6 以上で利用可。_

キー割り当てを削除。

[WARNING]
この関数を呼び出す際には、ユーザのキー割り当てを削除しないように注意してください。

プロトタイプ:

[source,C]
----
int weechat_key_unbind (const char *context, const char *key);
----

引数:

* 'context': キーのコンテキスト (<<_key_bind,weechat_key_bind>> を参照)
* 'key': 削除するキーまたは特殊値 "area:XXX" で1 番目または 2
  番目の領域から 'XXX' をもつすべてのキーを削除する

戻り値:

* 削除されたキー割り当ての個数

C 言語での使用例:

[source,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) での使用例:

[source,python]
----
# プロトタイプ
num_keys = weechat.key_unbind(context, key)

# 例

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

[[display]]
=== 表示

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

==== prefix

プレフィックスを返す。

プロトタイプ:

[source,C]
----
const char *weechat_prefix (const char *prefix);
----

引数:

* 'prefix': プレフィックスの名前 (以下の表を参照)

戻り値:

* プレフィックスの値
  (プレフィックスと色コードを含む文字列)、プレフィックスが見つからない場合は空文字列

List of prefixes:

[width="70%",cols="^2e,^1,^3,5",options="header"]
|===
| プレフィックス | 値 | 色     | 説明
| error   | `=!=` | yellow     | エラーメッセージ
| network | `--`  | magenta    | ネットワークからのメッセージ
| action  | `*`   | white      | 本人の動作
| join    | `-->` | lightgreen | 誰かが現在のチャットに参加
| quit    | `<--` | lightred   | 誰かが現在のチャットから退出
|===

[NOTE]
値と色はコマンド `/set` でカスタマイズできます。

C 言語での使用例:

[source,C]
----
weechat_printf (NULL, "%sThis is an error...", weechat_prefix ("error"));
----

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

[source,python]
----
# プロトタイプ
value = weechat.prefix(prefix)

# 例
weechat.prnt("", "%sThis is an error..." % weechat.prefix("error"))
----

==== color

表示する色コードを文字列で返す。

プロトタイプ:

[source,C]
----
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 言語での使用例:

[source,C]
----
weechat_printf (NULL, "Color: %sblue %sdefault color %syellow on red",
                weechat_color ("blue"),
                weechat_color ("chat"),
                weechat_color ("yellow,red"));
----

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

[source,python]
----
# プロトタイプ
value = weechat.color(color_name)

# 例
weechat.prnt("", "Color: %sblue %sdefault color %syellow on red"
    % (weechat.color("blue"), weechat.color("chat"), weechat.color("yellow,red")))
----

==== printf

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

プロトタイプ:

[source,C]
----
void weechat_printf (struct t_gui_buffer *buffer, const char *message, ...);
----

引数:

* 'buffer': バッファへのポインタ、NULL の場合は WeeChat バッファにメッセージを表示
* 'message': 表示するメッセージ

[NOTE]
メッセージに含まれる最初のタブ文字 ("\t") はメッセージのプレフィックスを分割するために使われます。 +
メッセージに複数のタブ文字が含まれ、プレフィックスを使いたくない場合は、空白、タブ文字、メッセージのように使ってください
(以下の例を参照): これでプレフィックスが無くなります
(タブ文字の前の空白は表示されません)。

[NOTE]
2 つ連続したタブ文字 ("\t")
がメッセージの最初にある場合、時刻は表示されず、メッセージの位置調整は行われません。さらにメッセージの時刻が
0 に設定されます。

C 言語での使用例:

[source,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) での使用例:

[source,python]
----
# プロトタイプ
weechat.prnt(buffer, message)

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

[NOTE]
この関数をスクリプトの中で実行するには "print" (Python の場合は "prnt") と綴ります。

==== printf_date

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

プロトタイプ:

[source,C]
----
void weechat_printf_date (struct t_gui_buffer *buffer, time_t date,
                          const char *message, ...);
----

引数:

* 'buffer': バッファへのポインタ、NULL の場合、メッセージは WeeChat バッファに表示
* 'date': メッセージの日付 (0 は現在の日付/時間を意味する)
* 'message': 表示するメッセージ

C 言語での使用例:

[source,C]
----
weechat_printf_date (NULL, time (NULL) - 120, "Hello, 2 minutes ago");
----

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

==== printf_tags

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

プロトタイプ:

[source,C]
----
void weechat_printf_tags (struct t_gui_buffer *buffer, const char *tags,
                          const char *message, ...);
----

引数:

* 'buffer': バッファへのポインタ、NULL の場合、メッセージは WeeChat バッファに表示
* 'tags': タグのコンマ区切りリスト
* 'message': 表示するメッセージ

C 言語での使用例:

[source,C]
----
weechat_printf_tags (NULL, "notify_message",
                     "Message with a tag 'notify_message'");
----

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

==== printf_date_tags

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

プロトタイプ:

[source,C]
----
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': タグのコンマ区切りリスト
* 'message': 表示するメッセージ

通常使用するタグ (一部抜粋したリスト):

[width="70%",cols="1m,4",options="header"]
|===
| タグ             | 説明
| no_filter        | フィルタできない行
| no_highlight     | ハイライトできない行
| no_log           | ログファイルに書き込まれない行
| log0 ... log9    | 行に対するログレベル (`/help logger` を参照)
| notify_none      | この行を含むバッファはホットリストに追加されない
| notify_message   | この行を含むバッファは "message" レベルでホットリストに追加される
| notify_private   | この行を含むバッファは "private" レベルでホットリストに追加される
| notify_highlight | この行を含むバッファは "highlight" レベルでホットリストに追加される
| nick_xxx         | ニックネーム "xxx" からのメッセージ
| prefix_nick_ccc  | プレフィックスを色 "ccc" のニックネームにする
| host_xxx         | メッセージ中のユーザ名とホスト
| irc_xxx          | IRC メッセージ "xxx" (コマンドまたは 3 桁の番号)
| irc_numeric      | IRC 番号メッセージ
| irc_error        | IRC からのエラー
| irc_action       | あるニックネームからのアクション (`/me` コマンド)
| irc_ctcp         | CTCP メッセージ
| irc_ctcp_reply   | CTCP メッセージに対する返信
| irc_smart_filter | "smart filter" でフィルタリング可能な IRC メッセージ
| away_info        | 離席状態のメッセージ
|===

C 言語での使用例:

[source,C]
----
weechat_printf_date_tags (NULL, time (NULL) - 120, "notify_message",
                          "Message 2 minutes ago, with a tag 'notify_message'");
----

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

[source,python]
----
# プロトタイプ
weechat.prnt_date_tags(buffer, date, tags, message)

# 例
time = int(time.time())
weechat.prnt_date_tags("", time - 120, "notify_message",
    "Message 2 minutes ago, with a tag 'notify_message'")
----

[NOTE]
この関数をスクリプトの中で実行するには "print_date_tags" (Python の場合は "prnt_date_tags") と綴ります。

==== printf_y

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

プロトタイプ:

[source,C]
----
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 言語での使用例:

[source,C]
----
weechat_printf_y (buffer, 2, "My message on third line");
----

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

[source,python]
----
# プロトタイプ
weechat.prnt_y(buffer, y, message)

# 例
weechat.prnt_y("", 2, "My message on third line")
----

[NOTE]
この関数をスクリプトの中で実行するには "print_y" (Python の場合は "prnt_y") と綴ります。

==== log_printf

WeeChat ログファイル (weechat.log) にメッセージを書き込む。

プロトタイプ:

[source,C]
----
void weechat_log_printf (const char *message, ...);
----

引数:

* 'message': 書き込むメッセージ

C 言語での使用例:

[source,C]
----
weechat_log_printf ("My message in log file");
----

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

[source,python]
----
# プロトタイプ
weechat.log_print(message)

# 例
weechat.log_print("My message in log file")
----

[NOTE]
この関数をスクリプトの中で実行するには "log_print" と綴ります。

[[hooks]]
=== フック

[[hook_priority]]
[float]
==== フックの優先度

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

一部のフックに対して優先度を設定することができます。フックリストは優先度の高い順にフックが並べられ、高い優先度を持つフックはそれよりも低い優先度を持つフックが実行される前に実行されます。これは実行順序が重要となる修飾子で便利です。

優先度が指定できる引数に優先度を設定するには、必ず以下の構文を使ってください:
"nnn|name" ここで "nnn" は優先度を示すゼロおよび正の整数で
"name" は引数の名前です
(優先度は自動的に文字列から削除され、フックの名前になります)。

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

C 言語での使用例:

[source,C]
----
/* hook modifier with priority = 2000 */
weechat_hook_modifier ("2000|input_text_display", &modifier_cb, NULL);
----

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

==== hook_command

コマンドをフックする。

プロトタイプ:

[source,C]
----
struct t_hook *weechat_hook_command (const char *command,
                                     const char *description,
                                     const char *args,
                                     const char *args_description,
                                     const char *completion,
                                     int (*callback)(void *data,
                                                     struct t_gui_buffer *buffer,
                                                     int argc,
                                                     char **argv,
                                                     char **argv_eol),
                                     void *callback_data);
----

引数:

* 'command': コマンド名
  (優先度の設定が可能、<<hook_priority,優先度>>に関する注意を参照)
* 'description': コマンドの説明 (`/help command` で表示されます)
* 'args': コマンドの引数 (`/help command` で表示されます)
* 'args_description': 引数の説明 (`/help command` で表示されます)
* 'completion': コマンドの補完候補テンプレート: 各引数に対する補完候補の空白区切りリスト。1
  つの引数に対して複数の補完候補を設定するには補完候補同士を "|"
  で区切ってください。1 つのコマンドに対して複数のテンプレートを設定するにはテンプレート同士を
  "||" で区切ってください。
* 'callback': コマンドが使用された際に呼び出す関数、引数と戻り値:
** 'void *data': ポインタ
** 'struct t_gui_buffer *buffer': コマンドを実行するバッファ
** 'int argc': コマンドに渡す引数の個数
** 'char **argv': コマンドに渡す引数
** 'char **argv_eol': コマンドに渡す引数
   (最初の引数から各引数までを収めた文字列)
** 戻り値:
*** 'WEECHAT_RC_OK'
*** 'WEECHAT_RC_ERROR'
* 'callback_data': WeeChat がコールバックを呼び出す際にコールバックに渡すポインタ

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

include::autogen/plugin_api/completions.asciidoc[]

特殊コード:

* '%%command': コマンド 'command' と同じ補完候補テンプレートを使用
* '%-': 補完の中止
* '%*': 最後の補完候補を繰り返す

戻り値:

* 新しいフックへのポインタ、エラーが起きた場合は NULL

C 言語での使用例:

[source,C]
----
int
my_command_cb (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 (/* command name */
                          "myfilter",
                          /* description */
                          "description of myfilter",
                          /* args */
                          "[list] | [enable|disable|toggle [name]] | "
                          "[add name plugin.buffer tags regex] | "
                          "[del name|-all]",
                          /* args description */
                          "description of arguments...",
                          /* completion */
                          "list"
                          " || enable %(filters_names)"
                          " || disable %(filters_names)"
                          " || toggle %(filters_names)"
                          " || add %(filters_names) %(buffers_plugins_names)|*"
                          " || del %(filters_names)|-all",
                          /* callback */
                          &my_command_cb,
                          /* callback_data */
                          NULL);
----

例えば、コマンドが `/command abc def ghi`
のように実行された場合、'argv' と 'argv_eol' は以下のようになります:

* 'argv':
** 'argv[0]' == "/command"
** 'argv[1]' == "abc"
** 'argv[2]' == "def"
** 'argv[3]' == "ghi"
* 'argv_eol':
** 'argv_eol[0]' == "/command abc def ghi"
** 'argv_eol[1]' == "abc def ghi"
** 'argv_eol[2]' == "def ghi"
** 'argv_eol[3]' == "ghi"

スクリプトでは、'args' は "abc def ghi" のようになります。

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

[source,python]
----
# プロトタイプ
hook = weechat.hook_command(command, description, args, args_description,
    completion, callback, callback_data)

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

==== hook_command_run

WeeChat がコマンドを実行する際にこれをフック。

プロトタイプ:

[source,C]
----
struct t_hook *weechat_hook_command_run (const char *command,
                                         int (*callback)(void *data,
                                                         struct t_gui_buffer *buffer,
                                                         const char *command),
                                         void *callback_data);
----

引数:

* 'command': フックするコマンド (ワイルドカード "*" を使うことができます)
  (優先度の設定が可能、<<hook_priority,優先度>>に関する注意を参照)
* 'callback': コマンドが実行される際に呼び出す関数、引数と戻り値:
** 'void *data': ポインタ
** 'struct t_gui_buffer *buffer': コマンドを実行するバッファ
** 'const char *command': 実行するコマンド、引数付き
** 戻り値:
*** 'WEECHAT_RC_OK'
*** 'WEECHAT_RC_OK_EAT'
*** 'WEECHAT_RC_ERROR'
* 'callback_data': WeeChat がコールバックを呼び出す際にコールバックに渡すポインタ

[NOTE]
コールバックは 'WEECHAT_RC_OK' または 'WEECHAT_RC_OK_EAT'
(コールバックの後にコマンドを実行しない) を返すことができます。

戻り値:

* 新しいフックへのポインタ、エラーが起きた場合は NULL

C 言語での使用例:

[source,C]
----
int
my_command_run_cb (void *data, struct t_gui_buffer *buffer,
                   const char *command)
{
    weechat_printf (NULL,
                    "You want to complete? I'm eating the completion ahah!");
    return WEECHAT_RC_OK_EAT;
}

struct t_hook *my_command_run_hook =
    weechat_hook_command_run ("/input complete*",
                              &my_command_run_cb, NULL);
----

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

[source,python]
----
# プロトタイプ
hook = weechat.hook_command_run(command, callback, callback_data)

# 例
def my_command_run_cb(data, buffer, command):
    weechat.prnt("", "You want to complete? I'm eating the completion, ahah!")
    return weechat.WEECHAT_RC_OK_EAT

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

==== hook_timer

タイマをフックする。

プロトタイプ:

[source,C]
----
struct t_hook *weechat_hook_timer (long interval,
                                   int align_second,
                                   int max_calls,
                                   int (*callback)(void *data,
                                                   int remaining_calls),
                                   void *callback_data);
----

引数:

* 'interval': 2 つの呼び出し間隔 (ミリ秒、1000 = 1 秒)
* 'align_second': 秒の調整。例えば、現在時刻が 09:00、
  interval = 60000 (60 秒)、align_second = 60
  の場合、毎分 0 秒時にタイマを呼び出す
* 'max_calls': タイマを呼び出す回数 (0 の場合、タイマを無限に呼び出す)
* 'callback': 時間が来たら呼び出す関数、引数と戻り値:
** 'void *data': ポインタ
** 'int remaining_calls': 呼び出し残り回数 (タイマを無限に呼び出す場合は -1)
** 戻り値:
*** 'WEECHAT_RC_OK'
*** 'WEECHAT_RC_ERROR'
* 'callback_data': WeeChat がコールバックを呼び出す際にコールバックに渡すポインタ

戻り値:

* 新しいフックへのポインタ、エラーが起きた場合は NULL

C 言語での使用例:

[source,C]
----
int
my_timer_cb (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);
----

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

[source,python]
----
# プロトタイプ
hook = weechat.hook_timer(interval, align_second, max_calls, callback, callback_data)

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

==== hook_fd

_バージョン 1.3 で更新。_

ファイルディスクリプタ (ファイルやソケット) をフック。

プロトタイプ:

[source,C]
----
struct t_hook *weechat_hook_fd (int fd,
                                int flag_read,
                                int flag_write,
                                int flag_exception,
                                int (*callback)(void *data,
                                                int fd),
                                void *callback_data);
----

引数:

* 'fd': ファイルディスクリプタ
* 'flag_read': 1 = 読み込みイベントをキャッチ、0 = 無視
* 'flag_write': 1 = 書き込みイベントをキャッチ、0 = 無視
// TRANSLATION MISSING
* 'flag_exception': 1 = 例外イベントをキャッチ、0 = 無視
  (_WeeChat ≥ 1.3_: this argument is ignored and not used any more)
* 'callback': ファイル (またはソケット) に対してキャッチしたいイベントが発生した場合に実行する関数、
  引数と戻り値:
** 'void *data': ポインタ
** 'int fd': ファイルディスクリプタ
** 戻り値:
*** 'WEECHAT_RC_OK'
*** 'WEECHAT_RC_ERROR'
* 'callback_data': WeeChat がコールバックを呼び出す際にコールバックに渡すポインタ

戻り値:

* 新しいフックへのポインタ、エラーが起きた場合は NULL

C 言語での使用例:

[source,C]
----
int
my_fd_cb (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);
----

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

[source,python]
----
# プロトタイプ
hook = weechat.hook_fd(fd, flag_read, flag_write, flag_exception, callback, callback_data)

# 例
def my_fd_cb(data, fd):
    # ...
    return weechat.WEECHAT_RC_OK

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

==== hook_process

プロセスをフックして (フォークして実行)、出力を受け取る。

[NOTE]
バージョン 0.3.9.2
以降、コマンドを実行するためにシェルを使わないようになりました。WeeChat
が自動的にコマンドと引数を分割します (シェルがやっているように)。 +
(コマンドのクォートに従った)
分割に失敗する場合、またはシェルを使いたい場合は、ハッシュテーブル
'options' に引数を入れて <<_hook_process_hashtable,weechat_hook_process_hashtable>>
関数を使ってください _(WeeChat バージョン 0.4.0 以上で利用可)_ 。

プロトタイプ:

[source,C]
----
struct t_hook *weechat_hook_process (const char *command,
                                     int timeout,
                                     int (*callback)(void *data,
                                                     const char *command,
                                                     int return_code,
                                                     const char *out,
                                                     const char *err),
                                     void *callback_data);
----


引数:

* 'command': 子プロセスで実行するコマンドまたは
  URL _(WeeChat バージョン 0.3.7 以上で利用可)_ (以下を参照)
* 'timeout': コマンドのタイムアウト (ミリ秒):
  このタイムアウトを過ぎたら、子プロセスを kill します (タイムアウトさせない場合は 0)
* 'callback':
  子プロセスからのデータが利用可能になるか、子プロセスが終了したら呼び出す関数、引数と戻り値:
** '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' (コマンドの実行中にエラー)
** 'out': コマンドの標準出力 (stdout)
** 'err': コマンドの標準エラー出力 (stderr)
** 戻り値:
*** 'WEECHAT_RC_OK'
*** 'WEECHAT_RC_ERROR'
* 'callback_data': WeeChat がコールバックを呼び出す際にコールバックに渡すポインタ

戻り値:

* 新しいフックへのポインタ、エラーが起きた場合は NULL

コマンドが終了するか、タイムアウトを過ぎた場合、WeeChat は自動的にフックを解除します
(プロセスが実行中であればプロセスを kill します)。

コマンドを "url:http://www.example.com" のフォーマットに従う URL にすることで、URL
の内容がダウンロードされます _(WeeChat バージョン 0.3.7 以上で利用可)_ 。<<_hook_process_hashtable,weechat_hook_process_hashtable>>
関数を使えば URL に対してオプションを与えることもできます。

[TIP]
WeeChat に関する情報 (例えば現在の安定版、最新の git コミット、...)
が欲しい場合、https://weechat.org/dev/info に書かれている URL を使ってください

[NOTE]
コールバックにデータを送信するバッファのサイズは 64KB (バッファは 2
つあります: 標準出力用と、標準エラー出力用)
です。子プロセスからの出力 (標準出力または標準エラー出力) が 64KB
よりも大きくなった場合は、コールバックを 1 回以上呼び出します。

[IMPORTANT]
コールバックを 1
回より多く呼び出すことが皆無だとしても、コールバックを複数回呼び出しても安全なようにコードを書いてください:
必ず複数回送られたデータを連結し、データを使うのは戻り値が正またはゼロの時だけにしてください。

C 言語での使用例:

[source,C]
----
int
my_process_cb (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);
----

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

[source,python]
----
# プロトタイプ
hook = weechat.hook_process(command, timeout, callback, callback_data)

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

==== hook_process_hashtable

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

ハッシュテーブルに収めたオプションを使いプロセスをフックする
(フォークして実行)、出力を受け取る。

プロトタイプ:

[source,C]
----
struct t_hook *weechat_hook_process_hashtable (const char *command,
                                               struct t_hashtable *options,
                                               int timeout,
                                               int (*callback)(void *data,
                                                               const char *command,
                                                               int return_code,
                                                               const char *out,
                                                               const char *err),
                                               void *callback_data);
----

引数は以下の追加引数を除いて
<<_hook_process,weechat_hook_process>> 関数と同じです:

* 'options': 実行するコマンドのオプション;
  ハッシュテーブルは関数の中で複製されるため、この関数を呼び出した後にハッシュテーブルを安全に開放できます。

一般的なコマンド (最初に "url:" が付かないコマンド)
では、以下のオプションを使うことができます:

[width="100%",cols="^1,1,3",options="header"]
|===
| オプション | 値 | 説明

| argN (N ≥ 1) +
  _(WeeChat バージョン 0.4.0 以上で利用可)_ |
  任意の文字列 |
  コマンドの引数;
  このオプションを使って引数を渡さない場合、シェルと同じように引数を自動的に分割します
  ('command' 引数からコマンド引数を読み込みます)

| stdin +
  _(WeeChat バージョン 0.4.3 以上で利用可)_ |
  (非使用) |
  データを書き込むためのパイプを子プロセスの標準入力 (stdin)
  に作成します (関数 <<_hook_set,weechat_hook_set>> を参照)

| buffer_flush +
  _(WeeChat バージョン 1.0 以上で利用可)_ |
  バイト数 |
  標準出力および標準エラー出力をフラッシュ (出力をコールバックに送信) するバイト数の最小値、
  1 から 65536 (デフォルト) まで; 1 = すべての出力をすぐにコールバックに送信

| detached +
  _(WeeChat バージョン 1.0 以上で利用可)_ |
  (非使用) |
  detached モードでプロセスを実行: 標準出力と標準エラー出力を
  '/dev/null' にリダイレクトする
|===

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

include::autogen/plugin_api/url_options.asciidoc[]

[NOTE]
^(1)^ 定数が利用可能な場合、定数は必ずオプションの値に含めてください。"mask"
型のオプションでは、以下のフォーマットに従ってください: "value1+value2+value3"。

URL では、入力/出力ファイル用に 2 つのオプション (文字列) を使うことができます:

* 'file_in': 読み込んで URL に送信するファイル (ファイルを送信)
* 'file_out': ダウンロードした URL/ファイルをこのファイルに書き込む
  (標準出力を使わない)

戻り値:

* 新しいフックへのポインタ、エラーが起きた場合は NULL

C 言語での使用例:

[source,C]
----
int
my_process_cb (void *data, const char *command, int return_code,
               const char *out, const char *err)
{
    if (return_code == WEECHAT_HOOK_PROCESS_ERROR)
    {
        weechat_printf (NULL, "Error with command '%s'", command);
        return WEECHAT_RC_OK;
    }

    if (return_code >= 0)
    {
        weechat_printf (NULL, "return_code = %d", return_code);
    }

    if (out)
    {
        weechat_printf (NULL, "stdout: %s", out);
    }

    if (err)
    {
        weechat_printf (NULL, "stderr: %s", err);
    }

    return WEECHAT_RC_OK;
}

/* 例 1: URL をダウンロード */
struct t_hashtable *options = weechat_hashtable_new (8,
                                                     WEECHAT_HASHTABLE_STRING,
                                                     WEECHAT_HASHTABLE_STRING,
                                                     NULL,
                                                     NULL);
if (options)
{
    weechat_hashtable_set (options, "file_out", "/tmp/weechat.org.html");
    struct t_hook *my_process_hook = weechat_hook_process_hashtable ("url:https://weechat.org/",
                                                                     options,
                                                                     20000,
                                                                     &my_process_cb, NULL);
    weechat_hashtable_free (options);
}

/* 例 2: メッセージを渡して通知プログラムを実行 */
struct t_hashtable *options_cmd1 = weechat_hashtable_new (8,
                                                          WEECHAT_HASHTABLE_STRING,
                                                          WEECHAT_HASHTABLE_STRING,
                                                          NULL,
                                                          NULL);
if (options_cmd1)
{
    weechat_hashtable_set (options_cmd1, "arg1", "-from");
    weechat_hashtable_set (options_cmd1, "arg2", nick);
    weechat_hashtable_set (options_cmd1, "arg3", "-msg");
    weechat_hashtable_set (options_cmd1, "arg4", message);  /* untrusted argument */
    struct t_hook *my_process_hook = weechat_hook_process_hashtable ("my-notify-command",
                                                                     options_cmd1,
                                                                     20000,
                                                                     &my_process_cb, NULL);
    weechat_hashtable_free (options_cmd1);
}

/* 例 3: コマンドを実行するためにシェルを呼び出す (必ず安全なコマンドを実行してください) */
struct t_hashtable *options_cmd2 = weechat_hashtable_new (8,
                                                          WEECHAT_HASHTABLE_STRING,
                                                          WEECHAT_HASHTABLE_STRING,
                                                          NULL,
                                                          NULL);
if (options_cmd2)
{
    weechat_hashtable_set (options_cmd2, "arg1", "-c");
    weechat_hashtable_set (options_cmd2, "arg2", "ls -l /tmp | grep something");
    struct t_hook *my_process_hook = weechat_hook_process_hashtable ("sh",
                                                                     options_cmd2,
                                                                     20000,
                                                                     &my_process_cb, NULL);
    weechat_hashtable_free (options_cmd2);
}
----

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

[source,python]
----
# プロトタイプ
hook = weechat.hook_process_hashtable(command, options, timeout, callback, callback_data)

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

# 例 1: URL をダウンロード
hook1 = weechat.hook_process_hashtable("url:https://weechat.org/",
                                       {"file_out": "/tmp/weechat.org.html"},
                                       20000, "my_process_cb", "")

# 例 2: メッセージを渡して通知プログラムを実行
hook2 = weechat.hook_process_hashtable("my-notify-command",
                                       {"arg1": "-from",
                                        "arg2": nick,
                                        "arg3": "-msg",
                                        "arg4": message},  # untrusted argument
                                       20000, "my_process_cb", "")

# 例 3: コマンドを実行するためにシェルを呼び出す (必ず安全なコマンドを実行してください)
hook3 = weechat.hook_process_hashtable("sh",
                                       {"arg1": "-c",
                                        "arg2": "ls -l /tmp | grep something"},
                                       20000, "my_process_cb", "")
----

==== hook_connect

接続をフックする (リモートホストへのバックグラウンド接続)。

プロトタイプ:

[source,C]
----
struct t_hook *weechat_hook_connect (const char *proxy,
                                     const char *address,
                                     int port,
                                     int ipv6,
                                     int retry,
                                     void *gnutls_sess,
                                     void *gnutls_cb,
                                     int gnutls_dhkey_size,
                                     const char *gnutls_priorities,
                                     const char *local_hostname,
                                     int (*callback)(void *data,
                                                     int status,
                                                     int gnutls_rc,
                                                     int sock,
                                                     const char *error,
                                                     const char *ip_address),
                                     void *callback_data);
----

引数:

* 'proxy': 接続に使用するプロキシの名前
  (任意、プロキシを使わない場合は NULL)
* 'address': 接続先のドメイン名または IP アドレス
* 'port': ポート番号
* 'ipv6': (IPv4 フォールバックを有効にして) IPv6 を使う場合は 1、IPv4 のみを使う場合は 0
* 'retry': 再試行回数、IPv6 ホストに接続したもののクライアントの受け入れに失敗した際に
  IPv4 ホストへフォールバックする際に使う
* 'gnutls_sess': GnuTLS セッション (任意)
* 'gnutls_cb': GnuTLS コールバック (任意)
* 'gnutls_dhkey_size': Diffie-Hellman
  鍵交換の際に使う鍵のサイズ (GnuTLS)
* 'gnutls_priorities': gnutls のプロパティ (構文は gnutls マニュアルの
  'gnutls_priority_init' 関数を参照)、基本的な値を以下に示す:
** 'PERFORMANCE'
** 'NORMAL' (デフォルト)
** 'SECURE128'
** 'SECURE256'
** 'EXPORT'
** 'NONE'
* 'local_hostname': 接続に使うローカルのホスト名前 (任意)
* 'callback':
  接続に成功および失敗した際に呼び出す関数、引数と戻り値:
** 'void *data': ポインタ
** 'int status': 接続状態:
*** 'WEECHAT_HOOK_CONNECT_OK': 接続成功
*** 'WEECHAT_HOOK_CONNECT_ADDRESS_NOT_FOUND': アドレスが見つかりません
*** 'WEECHAT_HOOK_CONNECT_IP_ADDRESS_NOT_FOUND': IP アドレスが見つかりません
*** 'WEECHAT_HOOK_CONNECT_CONNECTION_REFUSED': 接続が拒否されました
*** 'WEECHAT_HOOK_CONNECT_PROXY_ERROR': プロキシに関するエラー
*** 'WEECHAT_HOOK_CONNECT_LOCAL_HOSTNAME_ERROR': ローカルのホスト名に関するエラー
*** 'WEECHAT_HOOK_CONNECT_GNUTLS_INIT_ERROR': GnuTLS 初期化エラー
*** 'WEECHAT_HOOK_CONNECT_GNUTLS_HANDSHAKE_ERROR': GnuTLS ハンドシェイクエラー
*** 'WEECHAT_HOOK_CONNECT_MEMORY_ERROR': メモリ不足
*** 'WEECHAT_HOOK_CONNECT_TIMEOUT': タイムアウト
*** 'WEECHAT_HOOK_CONNECT_SOCKET_ERROR': ソケットの作成に失敗
** 'gnutls_rc': 'gnutls_handshake()' の戻り値
** 'sock': 接続に使うソケット
** 'const char *error': 'gnutls_strerror(gnutls_rc)' の戻り値
** 'const char *ip_address': 見つかった IP アドレス
** 戻り値:
*** 'WEECHAT_RC_OK'
*** 'WEECHAT_RC_ERROR'
* 'callback_data': WeeChat がコールバックを呼び出す際にコールバックに渡すポインタ

戻り値:

* 新しいフックへのポインタ、エラーが起きた場合は NULL

C 言語での使用例:

[source,C]
----
int
my_connect_cb (void *data, int status, int gnutls_rc, int sock,
               const char *error, const char *ip_address)
{
    switch (status)
    {
        case WEECHAT_HOOK_CONNECT_OK:
            /* ... */
            break;
        case WEECHAT_HOOK_CONNECT_ADDRESS_NOT_FOUND:
            /* ... */
            break;
        case WEECHAT_HOOK_CONNECT_IP_ADDRESS_NOT_FOUND:
            /* ... */
            break;
        case WEECHAT_HOOK_CONNECT_CONNECTION_REFUSED:
            /* ... */
            break;
        case WEECHAT_HOOK_CONNECT_PROXY_ERROR:
            /* ... */
            break;
        case WEECHAT_HOOK_CONNECT_LOCAL_HOSTNAME_ERROR:
            /* ... */
            break;
        case WEECHAT_HOOK_CONNECT_GNUTLS_INIT_ERROR:
            /* ... */
            break;
        case WEECHAT_HOOK_CONNECT_GNUTLS_HANDSHAKE_ERROR:
            /* ... */
            break;
        case WEECHAT_HOOK_CONNECT_MEMORY_ERROR:
            /* ... */
            break;
        case WEECHAT_HOOK_CONNECT_TIMEOUT:
            /* ... */
            break;
        case WEECHAT_HOOK_CONNECT_SOCKET_ERROR:
            /* ... */
            break;
    }
    return WEECHAT_RC_OK;
}

struct t_hook *my_connect_hook = weechat_hook_connect (NULL,
                                                       "my.server.org", 1234,
                                                       1, 0,
                                                       NULL, NULL, 0,  /* GnuTLS */
                                                       NULL,
                                                       &my_connect_cb, NULL);
----

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

[source,python]
----
# プロトタイプ
hook = weechat.hook_connect(proxy, address, port, ipv6, retry, local_hostname,
    callback, callback_data)

# 例
def my_connect_cb(data, status, gnutls_rc, sock, error, ip_address):
    if status == WEECHAT_HOOK_CONNECT_OK:
        # ...
    elif status == WEECHAT_HOOK_CONNECT_ADDRESS_NOT_FOUND:
        # ...
    elif status == WEECHAT_HOOK_CONNECT_IP_ADDRESS_NOT_FOUND:
        # ...
    elif status == WEECHAT_HOOK_CONNECT_CONNECTION_REFUSED:
        # ...
    elif status == WEECHAT_HOOK_CONNECT_PROXY_ERROR:
        # ...
    elif status == WEECHAT_HOOK_CONNECT_LOCAL_HOSTNAME_ERROR:
        # ...
    elif status == WEECHAT_HOOK_CONNECT_GNUTLS_INIT_ERROR:
        # ...
    elif status == WEECHAT_HOOK_CONNECT_GNUTLS_HANDSHAKE_ERROR:
        # ...
    elif status == WEECHAT_HOOK_CONNECT_MEMORY_ERROR:
        # ...
    elif status == WEECHAT_HOOK_CONNECT_TIMEOUT:
        # ...
    elif status == WEECHAT_HOOK_CONNECT_SOCKET_ERROR:
        # ...
    return weechat.WEECHAT_RC_OK

hook = weechat.hook_connect("", "my.server.org", 1234, 1, 0, "",
                            "my_connect_cb", "")
----

==== hook_print

_WeeChat バージョン 0.4.3 と 1.0 で更新_

メッセージの表示をフックする。

プロトタイプ:

[source,C]
----
struct t_hook *weechat_hook_print (struct t_gui_buffer *buffer,
                                   const char *tags,
                                   const char *message,
                                   int strip_colors,
                                   int (*callback)(void *data,
                                                   struct t_gui_buffer *buffer,
                                                   time_t date,
                                                   int tags_count,
                                                   const char **tags,
                                                   int displayed,
                                                   int highlight,
                                                   const char *prefix,
                                                   const char *message),
                                   void *callback_data);
----

引数:

* 'buffer': バッファへのポインタ、NULL の場合、任意のバッファからのメッセージをキャッチする
* 'tags': このタグが付けられたメッセージだけをキャッチする (任意):
** WeeChat バージョン 0.4.3 以上の場合: メッセージに付けられたタグのコンマ区切りリスト (論理 "or");
   複数の条件を論理 "and" で組み合わせる場合は区切りに "+" を使ってください;
   ワイルドカード "*" を使うことができます
** WeeChat バージョン 0.4.2 以下の場合: 論理 "and"
   で組み合わせたタグのコンマ区切りリスト
* 'message': この文字列を含むメッセージだけをキャッチする
  (任意、大文字小文字を区別しない)
* 'strip_colors': 1
  の場合、表示されるメッセージから色を削除する、コールバックを呼ぶ前
* 'callback':
  メッセージが表示される際に呼び出すコールバック、引数と戻り値:
** 'void *data': ポインタ
** 'struct t_gui_buffer *buffer': バッファへのポインタ
** 'time_t date': 日付
** 'int tags_count': 行に付けられたタグの個数
** 'const char **tags': 行に付けられたタグの配列
** 'int displayed': 行が表示される場合は 1、フィルタされる (隠される) 場合は 0
** 'int highlight': 行がハイライトされる場合は 1、ハイライトされない場合は 0
** 'const char *prefix': プレフィックス
** 'const char *message': メッセージ
** 戻り値:
*** 'WEECHAT_RC_OK'
*** 'WEECHAT_RC_ERROR'
* 'callback_data': WeeChat がコールバックを呼び出す際にコールバックに渡すポインタ

戻り値:

* 新しいフックへのポインタ、エラーが起きた場合は NULL

[IMPORTANT]
WeeChat バージョン 1.0 以上では、スクリプトのコールバック引数 'displayed'
と 'highlight' は整数です (WeeChat バージョン 0.4.3 以下では文字列でした)。 +
すべてのバージョンで互換性を持たせるためには、引数を使う前に整数に変換することをお勧めします、Python
を使った例: "`if int(highlight):`"。

C 言語での使用例:

[source,C]
----
int
my_print_cb (void *data, struct t_gui_buffer *buffer, time_t date,
             int tags_count, const char **tags,
             int displayed, int highlight,
             const char *prefix, const char *message)
{
    /* ... */
    return WEECHAT_RC_OK;
}

/* catch all messages, on all buffers, without color */
struct t_hook *my_print_hook =
    weechat_hook_print (NULL, NULL, NULL, 1, &my_print_cb, NULL);
----

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

[source,python]
----
# プロトタイプ
hook = weechat.hook_print(buffer, tags, message, strip_colors, callback, callback_data)

# 例
def my_print_cb(data, buffer, date, tags, displayed, highlight, prefix, message):
    if int(highlight):
        # ...
    return weechat.WEECHAT_RC_OK

# catch all messages, on all buffers, without color
hook = weechat.hook_print("", "", "", 1, "my_print_cb", "")
----

==== hook_signal

シグナルをフックする。

プロトタイプ:

[source,C]
----
struct t_hook *weechat_hook_signal (const char *signal,
                                    int (*callback)(void *data,
                                                    const char *signal,
                                                    const char *type_data,
                                                    void *signal_data),
                                    void *callback_data);
----

引数:

* 'signal': キャッチするシグナル、ワイルドカード "*" を使うことができます
  (優先度の設定が可能、<<hook_priority,優先度>>に関する注意を参照)
  (以下の表を参照)
* 'callback':
  シグナルを受信した際に呼び出す関数、引数と戻り値:
** 'void *data': ポインタ
** 'const char *signal': 受信したシグナル
** 'const char *type_data': シグナルが送信したデータの型
*** 'WEECHAT_HOOK_SIGNAL_STRING': 文字列
*** 'WEECHAT_HOOK_SIGNAL_INT': 整数
*** 'WEECHAT_HOOK_SIGNAL_POINTER':  ポインタ
** 'void *signal_data': シグナルが送信したデータ
** 戻り値:
*** 'WEECHAT_RC_OK'
*** 'WEECHAT_RC_OK_EAT' (直ちにシグナルの送信を止める)
    _(WeeChat バージョン 0.4.0 以上で利用可)_
*** 'WEECHAT_RC_ERROR'
* 'callback_data': WeeChat がコールバックを呼び出す際にコールバックに渡すポインタ

戻り値:

* 新しいフックへのポインタ、エラーが起きた場合は NULL

WeeChat とプラグインが送信するシグナルのリスト:

[width="100%",cols="^1,^3,4,5",options="header"]
|===
| プラグイン | シグナル | 引数 | 説明

| aspell | aspell_suggest +
  _(WeeChat バージョン 0.4.0 以上で利用可)_ |
  Pointer: バッファ |
  スペルの間違っている単語に対する新しい修正候補

| guile | guile_script_loaded +
  _(WeeChat バージョン 0.3.9 以上で利用可)_ |
  String: スクリプトへのパス |
  Scheme スクリプトを読み込み

| guile | guile_script_unloaded +
  _(WeeChat バージョン 0.3.9 以上で利用可)_ |
  String: スクリプトへのパス |
  Scheme スクリプトを再読み込み

| guile | guile_script_installed +
  _(WeeChat バージョン 0.3.9 以上で利用可)_ |
  String: インストールされたスクリプトへのパスのコンマ区切りリスト |
  Scheme スクリプトをインストール

| guile | guile_script_removed +
  _(WeeChat バージョン 0.3.9 以上で利用可)_ |
  String: 削除されたスクリプトへのパスのコンマ区切りリスト |
  Scheme スクリプトを削除

| irc | xxx,irc_in_yyy ^(1)^ |
  String: メッセージ |
  サーバから IRC メッセージを受信 (メッセージを*無視しない* 場合のみ irc
  プラグインがメッセージを処理する前に、シグナルが送信される)

| irc | xxx,irc_in2_yyy ^(1)^ |
  String: メッセージ |
  サーバから IRC メッセージを受信 (メッセージを*無視しない* 場合のみ irc
  プラグインがメッセージを処理した後に、シグナルが送信される)

| irc | xxx,irc_raw_in_yyy ^(1)^ +
  _(WeeChat バージョン 0.3.2 以上で利用可)_ |
  String: メッセージ |
  サーバから IRC メッセージを受信 (メッセージを無視する場合でも irc
  プラグインがメッセージを処理する前に、シグナルが送信される)

| irc | xxx,irc_raw_in2_yyy ^(1)^ +
  _(WeeChat バージョン 0.3.2 以上で利用可)_ |
  String: メッセージ |
  サーバから IRC メッセージを受信 (メッセージを無視する場合でも irc
  プラグインがメッセージを処理した後に、シグナルが送信される)

| irc | xxx,irc_out1_yyy ^(1)^ +
  _(WeeChat バージョン 0.3.7 以上で利用可)_ |
  String: メッセージ |
  サーバに IRC メッセージを送信 (メッセージを 512 バイトに合わせて自動分割する前)

| irc | xxx,irc_out_yyy ^(1)^ |
  String: メッセージ |
  サーバに IRC メッセージを送信 (メッセージを 512 バイトに合わせて自動分割した後)

| irc | xxx,irc_outtags_yyy ^(1)^ +
  _(WeeChat バージョン 0.3.4 以上で利用可)_ |
  String: タグ  + ";" + メッセージ |
  タグ + サーバに送信する IRC メッセージ

| irc | irc_ctcp |
  String: メッセージ |
  CTCP を受信

| irc | irc_dcc |
  String: メッセージ |
  新しい DCC

| irc | irc_pv |
  String: メッセージ |
  プライベートメッセージを受信

| irc | irc_channel_opened |
  Pointer: バッファ |
  チャンネルを開いた

| irc | irc_pv_opened |
  Pointer: バッファ |
  プライベートメッセージを開いた

| irc | irc_server_opened +
  _(WeeChat バージョン 0.3.7 以上で利用可)_ |
  Pointer: バッファ |
  サーババッファを開いた

| irc | irc_server_connecting |
  String: サーバ名 |
  サーバに接続中

| irc | irc_server_connected |
  String: サーバ名 |
  サーバとの接続を確立

| irc | irc_server_disconnected |
  String: サーバ名 |
  サーバから切断された

| irc | irc_ignore_removing |
  Pointer: 無視 |
  無視条件を削除中

| irc | irc_ignore_removed |
  - |
  無視条件を削除した

| irc | irc_notify_join +
  _(WeeChat バージョン 0.3.8 以上で利用可)_ |
  String: サーバ名 + "," + ニックネーム |
  通知リストに入っているニックネームがサーバに参加

| irc | irc_notify_quit +
  _(WeeChat バージョン 0.3.8 以上で利用可)_ |
  String: サーバ名 + "," + ニックネーム |
  通知リストに入っているニックネームがサーバから切断

| irc | irc_notify_away +
  _(WeeChat バージョン 0.3.8 以上で利用可)_ |
  String: サーバ名 + "," + ニックネーム + "," + 離席メッセージ |
  通知リストに入っているニックネームが離席状態に

| irc | irc_notify_still_away +
  _(WeeChat バージョン 0.3.8 以上で利用可)_ |
  String: サーバ名 + "," + ニックネーム + "," + 離席メッセージ |
  通知リストに入っているニックネームはまだ離席状態 (離席メッセージを変更)

| irc | irc_notify_back +
  _(WeeChat バージョン 0.3.8 以上で利用可)_ |
  String: サーバ名 + "," + ニックネーム |
  通知リストに入っているニックネームが着席状態に (離席状態を解除)

| javascript | javascript_script_loaded +
  _(WeeChat バージョン 1.2 以上で利用可)_ |
  String: スクリプトへのパス |
  Javascript スクリプトを読み込み

| javascript | javascript_script_unloaded +
  _(WeeChat バージョン 1.2 以上で利用可)_ |
  String: スクリプトへのパス |
  Javascript スクリプトを再読み込み

| javascript | javascript_script_installed +
  _(WeeChat バージョン 1.2 以上で利用可)_ |
  String: インストールされたスクリプトへのパスのコンマ区切りリスト |
  Javascript スクリプトをインストール

| javascript | javascript_script_removed +
  _(WeeChat バージョン 1.2 以上で利用可)_ |
  String: 削除されたスクリプトへのパスのコンマ区切りリスト |
  Javascript スクリプトを削除

| logger | logger_start |
  Pointer: バッファ |
  バッファのログ保存を開始

| logger | logger_stop |
  Pointer: バッファ |
  バッファのログ保存を中止

| logger | logger_backlog |
  Pointer: バッファ |
  バッファのバックログを表示

| lua | lua_script_loaded +
  _(WeeChat バージョン 0.3.9 以上で利用可)_ |
  String: スクリプトへのパス |
  Lua スクリプトを読み込み

| lua | lua_script_unloaded +
  _(WeeChat バージョン 0.3.9 以上で利用可)_ |
  String: スクリプトへのパス |
  Lua スクリプトを再読み込み

| lua | lua_script_installed +
  _(WeeChat バージョン 0.3.9 以上で利用可)_ |
  String: インストールされたスクリプトへのパスのコンマ区切りリスト |
  Lua スクリプトをインストール

| lua | lua_script_removed +
  _(WeeChat バージョン 0.3.9 以上で利用可)_ |
  String: 削除されたスクリプトへのパスのコンマ区切りリスト |
  Lua スクリプトを削除

| perl | perl_script_loaded +
  _(WeeChat バージョン 0.3.9 以上で利用可)_ |
  String: スクリプトへのパス |
  Perl スクリプトを読み込み

| perl | perl_script_unloaded +
  _(WeeChat バージョン 0.3.9 以上で利用可)_ |
  String: スクリプトへのパス |
  Perl スクリプトを再読み込み

| perl | perl_script_installed +
  _(WeeChat バージョン 0.3.9 以上で利用可)_ |
  String: インストールされたスクリプトへのパスのコンマ区切りリスト |
  Perl スクリプトをインストール

| perl | perl_script_removed +
  _(WeeChat バージョン 0.3.9 以上で利用可)_ |
  String: 削除されたスクリプトへのパスのコンマ区切りリスト |
  Perl スクリプトを削除

| python | python_script_loaded +
  _(WeeChat バージョン 0.3.9 以上で利用可)_ |
  String: スクリプトへのパス |
  Python スクリプトを読み込み

| python | python_script_unloaded +
  _(WeeChat バージョン 0.3.9 以上で利用可)_ |
  String: スクリプトへのパス |
  Python スクリプトを再読み込み

| python | python_script_installed +
  _(WeeChat バージョン 0.3.9 以上で利用可)_ |
  String: インストールされたスクリプトへのパスのコンマ区切りリスト |
  Python スクリプトをインストール

| python | python_script_removed +
  _(WeeChat バージョン 0.3.9 以上で利用可)_ |
  String: 削除されたスクリプトへのパスのコンマ区切りリスト |
  Python スクリプトを削除

| relay | relay_client_connecting +
  _(WeeChat バージョン 1.0 以上で利用可)_ |
  Pointer: リレークライアント |
  リレークライアントが接続中

| relay | relay_client_waiting_auth +
  _(WeeChat バージョン 1.0 以上で利用可)_ |
  Pointer: リレークライアント |
  リレークライアントからの認証待ち

| relay | relay_client_auth_ok +
  _(WeeChat バージョン 1.0 以上で利用可)_ |
  Pointer: リレークライアント |
  リレークライアントからの認証に成功

| relay | relay_client_connected +
  _(WeeChat バージョン 1.0 以上で利用可)_ |
  Pointer: リレークライアント |
  リレークライアントが接続

| relay | relay_client_auth_failed +
  _(WeeChat バージョン 1.0 以上で利用可)_ |
  Pointer: リレークライアント |
  リレークライアントの認証に失敗

| relay | relay_client_disconnected +
  _(WeeChat バージョン 1.0 以上で利用可)_ |
  Pointer: リレークライアント |
  リレークライアントが切断

| ruby | ruby_script_loaded +
  _(WeeChat バージョン 0.3.9 以上で利用可)_ |
  String: スクリプトへのパス |
  Ruby スクリプトを読み込み

| ruby | ruby_script_unloaded +
  _(WeeChat バージョン 0.3.9 以上で利用可)_ |
  String: スクリプトへのパス |
  Ruby スクリプトを再読み込み

| ruby | ruby_script_installed +
  _(WeeChat バージョン 0.3.9 以上で利用可)_ |
  String: インストールされたスクリプトへのパスのコンマ区切りリスト |
  Ruby スクリプトをインストール

| ruby | ruby_script_removed +
  _(WeeChat バージョン 0.3.9 以上で利用可)_ |
  String: 削除されたスクリプトへのパスのコンマ区切りリスト |
  Ruby スクリプトを削除

| tcl | tcl_script_loaded +
  _(WeeChat バージョン 0.3.9 以上で利用可)_ |
  String: スクリプトへのパス |
  Tcl スクリプトを読み込み

| tcl | tcl_script_unloaded +
  _(WeeChat バージョン 0.3.9 以上で利用可)_ |
  String: スクリプトへのパス |
  Tcl スクリプトを再読み込み

| tcl | tcl_script_installed +
  _(WeeChat バージョン 0.3.9 以上で利用可)_ |
  String: インストールされたスクリプトへのパスのコンマ区切りリスト |
  Tcl スクリプトをインストール

| tcl | tcl_script_removed +
  _(WeeChat バージョン 0.3.9 以上で利用可)_ |
  String: 削除されたスクリプトへのパスのコンマ区切りリスト |
  Tcl スクリプトを削除

| weechat | buffer_opened |
  Pointer: バッファ |
  バッファを開いた

| weechat | buffer_closing |
  Pointer: バッファ |
  バッファを閉じている

| weechat | buffer_closed |
  Pointer: バッファ |
  バッファを閉じた

| weechat | buffer_cleared |
  Pointer: バッファ |
  バッファをクリア

| weechat | buffer_hidden |
  Pointer: バッファ |
  バッファを隠す

| weechat | buffer_unhidden |
  Pointer: バッファ |
  バッファを隠すことを止める

| weechat | buffer_line_added +
  _(WeeChat バージョン 0.3.7 以上で利用可)_ |
  Pointer: 行 |
  バッファに行を追加

| weechat | buffer_lines_hidden |
  Pointer: バッファ |
  バッファから行を隠す

| weechat | buffer_localvar_added |
  Pointer: バッファ |
  ローカル変数を追加

| weechat | buffer_localvar_changed |
  Pointer: バッファ |
  ローカル変数を変更

| weechat | buffer_localvar_removed |
  Pointer: バッファ |
  ローカル変数を削除

| weechat | buffer_merged |
  Pointer: バッファ |
  バッファをマージ

| weechat | buffer_unmerged |
  Pointer: バッファ |
  バッファのマージを解除

| weechat | buffer_moved |
  Pointer: バッファ |
  バッファを移動

| weechat | buffer_renamed |
  Pointer: バッファ |
  バッファの名前を変更

| weechat | buffer_switch |
  Pointer: バッファ |
  バッファを切り替え

| weechat | buffer_title_changed |
  Pointer: バッファ |
  バッファのタイトルを変更

| weechat | buffer_type_changed |
  Pointer: バッファ |
  バッファのタイプを変更

| weechat | buffer_zoomed +
  _(WeeChat バージョン 0.4.3 以上で利用可)_ |
  Pointer: バッファ |
  マージされたバッファをズーム

| weechat | buffer_unzoomed +
  _(WeeChat バージョン 0.4.3 以上で利用可)_ |
  Pointer: バッファ |
  マージされたバッファをアンズーム

| weechat | day_changed +
  _(WeeChat バージョン 0.3.2 以上で利用可)_ |
  String: 新しい日付、フォーマット: "2010-01-31" |
  システムの日付が変更された

| weechat | debug_dump |
  String: プラグイン名 |
  リクエストをダンプ

| weechat | debug_libs |
  - |
  使用中の外部ライブラリを表示

| weechat | filter_added |
  Pointer: フィルタ |
  フィルタを追加

| weechat | filter_removing |
  Pointer: フィルタ |
  フィルタを削除中

| weechat | filter_removed |
  - |
  フィルタを削除

| weechat | filters_enabled |
  - |
  フィルタを有効化

| weechat | filters_disabled |
  - |
  フィルタを無効化

| weechat | hotlist_changed |
  - |
  ホットリストが変更された

| weechat | input_paste_pending |
  - |
  貼り付けを保留中

| weechat | input_search |
  Pointer: バッファ |
  バッファテキストの検索

| weechat | input_text_changed |
  Pointer: バッファ |
  入力テキストが変更された

| weechat | input_text_cursor_moved |
  Pointer: バッファ |
  入力テキストカーソルを移動

| weechat | key_bind |
  String: キー |
  キー割り当てを追加

| weechat | key_unbind |
  String: キー |
  キー割り当てを削除

| weechat | key_pressed |
  String: 押されたキー |
  キーが押された

| weechat | key_combo_default +
  _(WeeChat バージョン 1.0 以上で利用可)_ |
  String: キーの組み合わせ |
  'default' コンテキスト内のキーの組み合わせ

| weechat | key_combo_search +
  _(WeeChat バージョン 1.0 以上で利用可)_ |
  String: キーの組み合わせ |
  'search' コンテキスト内のキーの組み合わせ

| weechat | key_combo_cursor +
  _(WeeChat バージョン 1.0 以上で利用可)_ |
  String: キーの組み合わせ |
  'cursor' コンテキスト内のキーの組み合わせ

| weechat | mouse_enabled +
  _(WeeChat バージョン 1.1 以上で利用可)_ |
  - |
  マウスが有効化された

| weechat | mouse_disabled +
  _(WeeChat バージョン 1.1 以上で利用可)_ |
  - |
  マウスが無効化された

| weechat | nicklist_group_added +
  _(WeeChat バージョン 0.3.2 以上で利用可)_ |
  String: バッファポインタ + "," + グループ名 |
  ニックネームリストにグループを追加

| weechat | nicklist_group_changed +
  _(WeeChat バージョン 0.3.4 以上で利用可)_ |
  String: バッファポインタ + "," + グループ名 |
  ニックネームリストのグループを変更

| weechat | nicklist_group_removing +
  _(WeeChat バージョン 0.4.1 以上で利用可)_ |
  String: バッファポインタ + "," + グループ名 |
  ニックネームリストからグループを削除中

| weechat | nicklist_group_removed +
  _(WeeChat バージョン 0.3.2 以上で利用可)_ |
  String: バッファポインタ + "," + グループ名 |
  ニックネームリストからグループを削除

| weechat | nicklist_nick_added +
  _(WeeChat バージョン 0.3.2 以上で利用可)_ |
  String: バッファポインタ + "," + ニックネーム |
  ニックネームリストにニックネームを追加

| weechat | nicklist_nick_changed +
  _(WeeChat バージョン 0.3.4 以上で利用可)_ |
  String: バッファポインタ + "," + ニックネーム |
  ニックネームリストのニックネームを変更

| weechat | nicklist_nick_removing +
  _(WeeChat バージョン 0.4.1 以上で利用可)_ |
  String: バッファポインタ + "," + ニックネーム |
  ニックネームリストからニックネームを削除中

| weechat | nicklist_nick_removed +
  _(WeeChat バージョン 0.3.2 以上で利用可)_ |
  String: バッファポインタ + "," + ニックネーム |
  ニックネームリストからニックネームを削除

| weechat | partial_completion |
  - |
  部分補完を実行

| weechat | plugin_loaded +
  _(WeeChat バージョン 0.3.9 以上で利用可)_ |
  String: 読み込んだプラグインへのパス |
  プラグインを読み込み

| weechat | plugin_unloaded +
  _(WeeChat バージョン 0.3.9 以上で利用可)_ |
  String: 再読み込みしたプラグインの名前 (例: "irc") |
  プラグインを再読み込み

| weechat | quit |
  String: /quit の引数 |
  ユーザがコマンド `/quit` を実行

| weechat | signal_sighup +
  _(WeeChat バージョン 1.3 以上で利用可)_ |
  - |
  SIGHUP シグナルを受信

| weechat | signal_sigquit +
  _(WeeChat バージョン 1.2 以上で利用可)_ |
  - |
  SIGQUIT シグナルを受信 (コアダンプ付きで終了要求)

| weechat | signal_sigterm +
  _(WeeChat バージョン 1.2 以上で利用可)_ |
  - |
  SIGTERM シグナルを受信 (WeeChat プロセスを正常に終了させる)

| weechat | signal_sigwinch +
  _(WeeChat バージョン 0.4.3 以上で利用可)_ |
  - |
  SIGWINCH シグナルを受信しました (端末サイズが変更されました)

| weechat | upgrade |
  String: /upgrade に "-quit" 引数が与えられた場合は "quit"、それ以外は NULL |
  ユーザがコマンド `/upgrade` を実行

| weechat | upgrade_ended +
  _(WeeChat バージョン 0.3.4 以上で利用可)_ |
  - |
  アップグレード作業 (コマンド `/upgrade`) が終了

| weechat | weechat_highlight |
  String: プレフィックス付のメッセージ |
  メッセージがハイライトされました

| weechat | weechat_pv |
  String: プレフィックス付のメッセージ |
  プライベートメッセージの表示

| weechat | window_closing +
  _(WeeChat バージョン 0.3.6 以上で利用可)_ |
  Pointer: ウィンドウ |
  ウィンドウを閉じています

| weechat | window_closed +
  _(WeeChat バージョン 0.3.6 以上で利用可)_ |
  Pointer: ウィンドウ |
  ウィンドウを閉じた

| weechat | window_opened +
  _(WeeChat バージョン 0.4.1 以上で利用可)_ |
  Pointer: ウィンドウ |
  ウィンドウを開いた

| weechat | window_scrolled |
  Pointer: ウィンドウ |
  ウィンドウをスクロール

| weechat | window_switch +
  _(WeeChat バージョン 0.3.7 以上で利用可)_ |
  Pointer: ウィンドウ |
  ウィンドウを切り替え

| weechat | window_zoom |
  Pointer: 現在のウィンドウ |
  ウィンドウをズーム中

| weechat | window_zoomed |
  Pointer: 現在のウィンドウ |
  ウィンドウをズーム

| weechat | window_unzoom |
  Pointer: 現在のウィンドウ |
  ウィンドウのズームを元に戻している

| weechat | window_unzoomed |
  Pointer: 現在のウィンドウ |
  ウィンドウのズームを元に戻す

| xfer | xfer_add |
  Pointer: xfer 情報を含む infolist |
  新しい xfer

| xfer | xfer_send_ready |
  Pointer: xfer 情報を含む infolist |
  Xfer の準備完了

| xfer | xfer_accept_resume |
  Pointer: xfer 情報を含む infolist |
  Xfer のレジュームを受け入れる

| xfer | xfer_send_accept_resume |
  Pointer: xfer 情報を含む infolist |
  Xfer のレジュームの受け入れを完了

| xfer | xfer_start_resume |
  Pointer: xfer 情報を含む infolist |
  レジュームの開始

| xfer | xfer_resume_ready |
  Pointer: xfer 情報を含む infolist |
  Xfer レジュームの準備完了

| xfer | xfer_ended +
  _(WeeChat バージョン 0.3.2 以上で利用可)_ |
  Pointer: xfer 情報を含む infolist |
  Xfer を終了
|===

[NOTE]
^(1)^ 'xxx' はサーバ名、'yyy' は IRC コマンド名。

C 言語での使用例:

[source,C]
----
int
my_signal_cb (void *data, const char *signal, const char *type_data,
              void *signal_data)
{
    /* ... */
    return WEECHAT_RC_OK;
}

/* catch signal "quit" */
struct t_hook *my_signal_hook = weechat_hook_signal ("quit",
                                                     &my_signal_cb, NULL);
----

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

[source,python]
----
# プロトタイプ
hook = weechat.hook_signal(signal, callback, callback_data)

# 例
def my_signal_cb(data, signal, signal_data):
    # ...
    return weechat.WEECHAT_RC_OK

# catch signal "quit"
hook = weechat.hook_signal("quit", "my_signal_cb", "")
----

==== hook_signal_send

_バージョン 1.0 で更新。_

シグナルを送信。

プロトタイプ:

[source,C]
----
int weechat_hook_signal_send (const char *signal, const char *type_data,
                              void *signal_data);
----

引数:

* 'signal': 送信するシグナル
* 'type_data': シグナルと一緒に送信するデータの型
  (<<_hook_signal,weechat_hook_signal>> を参照)
* 'signal_data': シグナルと一緒に送信するデータ

戻り値 _(WeeChat バージョン 1.0 以上で利用可。)_:

* 最後に実行したコールバックの戻り値
  (コールバックを実行しなかった場合は 'WEECHAT_RC_OK'):
** 'WEECHAT_RC_OK'
** 'WEECHAT_RC_OK_EAT'
** 'WEECHAT_RC_ERROR'

C 言語での使用例:

[source,C]
----
int rc = weechat_hook_signal_send ("my_signal", WEECHAT_HOOK_SIGNAL_STRING, my_string);
----

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

[source,python]
----
# プロトタイプ
rc = weechat.hook_signal_send(signal, type_data, signal_data)

# 例
rc = weechat.hook_signal_send("my_signal", weechat.WEECHAT_HOOK_SIGNAL_STRING, my_string)
----

[[signal_logger_backlog]]
===== logger_backlog シグナル

シグナル "logger_backlog" はバッファにバックログ (チャット履歴)
を表示するために送信することができます (例えば、プラグインやスクリプトでバッファを開く際など)。

引数はバッファへのポインタ。

C 言語での使用例:

[source,C]
----
weechat_hook_signal_send ("logger_backlog", WEECHAT_HOOK_SIGNAL_POINTER, buffer);
----

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

[source,python]
----
weechat.hook_signal_send("logger_backlog", weechat.WEECHAT_HOOK_SIGNAL_POINTER, buffer)
----

[[signals_xxx_script_install]]
===== xxx_script_install シグナル

プログラミング言語ごとに、スクリプトをインストールするために送信するシグナルが 5 種類あります:

* 'perl_script_install'
* 'python_script_install'
* 'ruby_script_install'
* 'lua_script_install'
* 'tcl_script_install'
* 'guile_script_install'
* 'javascript_script_install'

シグナルを受け取ったらコールバックは以下のように働きます:

. インストール済みスクリプトを再読み込みして削除。
. 新しいスクリプトをディレクトリ '~/.weechat/xxx/' に移動 ('xxx' はプログラミング言語)
. 新しいスクリプトへのリンクをディレクトリ '~/.weechat/xxx/autoload/' に作成
. 新しいスクリプトを読み込む

'script' プラグインはスクリプトをインストールする際にこれらのシグナルを使っています。

引数はインストールするスクリプトのパスを収めた文字列です。

C 言語での使用例:

[source,C]
----
weechat_hook_signal_send ("python_script_install", WEECHAT_HOOK_SIGNAL_STRING,
                          "/home/xxx/.weechat/test.py");
----

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

[source,python]
----
weechat.hook_signal_send("python_script_install", WEECHAT_HOOK_SIGNAL_STRING,
                         "/home/xxx/.weechat/test.py")
----

[[signals_xxx_script_remove]]
===== xxx_script_remove シグナル

プログラミング言語ごとに、リスト文字列に含まれるスクリプトを削除するために送信するシグナルが 5 種類あります:

* 'perl_script_remove'
* 'python_script_remove'
* 'ruby_script_remove'
* 'lua_script_remove'
* 'tcl_script_remove'
* 'guile_script_remove'
* 'javascript_script_remove'

リスト文字列に含まれるそれぞれのスクリプトについて、コールバックはスクリプトを再読み込みして削除します。

'script' プラグインはスクリプトを削除する際にこれらのシグナルを使っています。

引数は削除したいスクリプトのコンマ区切りリスト文字列です
(パスを含まないスクリプトの名前を使います、例えば 'script.py').

C 言語での使用例:

[source,C]
----
/* unload and remove scripts test.py and script.py */
weechat_hook_signal_send ("python_script_remove", WEECHAT_HOOK_SIGNAL_STRING,
                          "test.py,script.py");
----

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

[source,python]
----
# unload and remove scripts test.py and script.py
weechat.hook_signal_send("python_script_remove", WEECHAT_HOOK_SIGNAL_STRING,
                         "test.py,script.py")
----

[[signal_irc_input_send]]
===== irc_input_send シグナル

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

irc バッファ(サーバ、チャンネル、プライベート)
への入力をシミュレートするにはシグナル "irc_input_send" を送信してください。

引数は以下のフォーマットに従う文字列です:

* 内部サーバ名 (必須)
* セミコロン
* チャンネル名 (任意)
* セミコロン
* メッセージを送信する際に使うフラグ (任意、デフォルトは 1):
** '1': 高い優先度を持つキュー (ユーザメッセージなどと同等)
** '2': 低い優先度を持つキュー (WeeChat が自動的に送信するメッセージと同等)
* セミコロン
* メッセージを送信する際に使うタグのコンマ区切りリスト (任意)
* セミコロン
* テキストまたはコマンド (必須)

C 言語での使用例:

[source,C]
----
/* say "Hello!" on freenode server, #weechat channel */
weechat_hook_signal_send ("irc_input_send", WEECHAT_HOOK_SIGNAL_STRING,
                          "freenode;#weechat;1;;Hello!");

/* send command "/whois FlashCode" on freenode server, with low priority */
weechat_hook_signal_send ("irc_input_send", WEECHAT_HOOK_SIGNAL_STRING,
                          "freenode;;2;;/whois FlashCode");
----

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

[source,python]
----
# say "Hello!" on freenode server, #weechat channel
weechat.hook_signal_send("irc_input_send", weechat.WEECHAT_HOOK_SIGNAL_STRING,
                         "freenode;#weechat;1;;Hello!")

# send command "/whois FlashCode" on freenode server, with low priority
weechat.hook_signal_send("irc_input_send", weechat.WEECHAT_HOOK_SIGNAL_STRING,
                         "freenode;;2;;/whois FlashCode")
----

==== hook_hsignal

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

hsignal (ハッシュテーブルを持つシグナル) をフック。

プロトタイプ:

[source,C]
----
struct t_hook *weechat_hook_hsignal (const char *signal,
                                     int (*callback)(void *data,
                                                     const char *signal,
                                                     struct t_hashtable *hashtable),
                                     void *callback_data);
----

Arguments:

* 'signal': キャッチするシグナル、ワイルドカード "*" を使うことができます
  (優先度の設定が可能、<<hook_priority,優先度>>に関する注意を参照)
  (以下の表を参照)
* 'callback':
  シグナルを受信した際に呼び出す関数、引数と戻り値:
** 'void *data': ポインタ
** 'const char *signal': 受信したシグナル
** 'struct t_hashtable *hashtable': ハッシュテーブル
** 戻り値:
*** 'WEECHAT_RC_OK'
*** 'WEECHAT_RC_OK_EAT' (直ちにシグナルの送信を止める)
    _(WeeChat バージョン 0.4.0 以上で利用可)_
*** 'WEECHAT_RC_ERROR'
* 'callback_data': WeeChat がコールバックを呼び出す際にコールバックに渡すポインタ

戻り値:

* 新しいフックへのポインタ、エラーが起きた場合は NULL

hsignal のリスト:

[width="100%",cols="^1,^3,5,5",options="header"]
|===
| プラグイン | シグナル | 引数 | 説明

| irc | irc_redirection_xxx_yyy ^(1)^ +
  _(WeeChat バージョン 0.3.4 以上で利用可)_ |
  <<hsignal_irc_redirect_command,hsignal_irc_redirect_command>> を参照 |
  出力の転送

| weechat | nicklist_group_added +
  _(WeeChat バージョン 0.4.1 以上で利用可)_ |
  'buffer' ('struct t_gui_buffer *'): バッファ +
  'parent_group' ('struct t_gui_nick_group *'): 親グループ +
  'group' ('struct t_gui_nick_group *'): グループ |
  ニックネームリストにグループを追加

| weechat | nicklist_nick_added +
  _(WeeChat バージョン 0.4.1 以上で利用可)_ |
  'buffer' ('struct t_gui_buffer *'): バッファ +
  'parent_group' ('struct t_gui_nick_group *'): 親グループ +
  'nick' ('struct t_gui_nick *'): ニックネーム |
  ニックネームリストにニックネームを追加

| weechat | nicklist_group_removing +
  _(WeeChat バージョン 0.4.1 以上で利用可)_ |
  'buffer' ('struct t_gui_buffer *'): バッファ +
  'parent_group' ('struct t_gui_nick_group *'): 親グループ +
  'group' ('struct t_gui_nick_group *'): グループ |
  ニックネームリストからグループを削除

| weechat | nicklist_nick_removing +
  _(WeeChat バージョン 0.4.1 以上で利用可)_ |
  'buffer' ('struct t_gui_buffer *'): バッファ +
  'parent_group' ('struct t_gui_nick_group *'): 親グループ +
  'nick' ('struct t_gui_nick *'): ニックネーム |
  ニックネームリストからニックネームを削除

| weechat | nicklist_group_changed +
  _(WeeChat バージョン 0.4.1 以上で利用可)_ |
  'buffer' ('struct t_gui_buffer *'): バッファ +
  'parent_group' ('struct t_gui_nick_group *'): 親グループ +
  'group' ('struct t_gui_nick_group *'): グループ |
  ニックネームリストに含まれるグループを変更

| weechat | nicklist_nick_changed +
  _(WeeChat バージョン 0.4.1 以上で利用可)_ |
  'buffer' ('struct t_gui_buffer *'): バッファ +
  'parent_group' ('struct t_gui_nick_group *'): 親グループ +
  'nick' ('struct t_gui_nick *'): ニックネーム |
  ニックネームリストに含まれるニックネームを変更
|===

[NOTE]
^(1)^ 'xxx' は転送で送信するシグナル、'yyy'
は転送元のシグナル。

C 言語での使用例:

[source,C]
----
int
my_hsignal_cb (void *data, const char *signal, struct t_hashtable *hashtable)
{
    /* ... */
    return WEECHAT_RC_OK;
}

struct t_hook *my_hsignal_hook = weechat_hook_hsignal ("test",
                                                       &my_hsignal_cb, NULL);
----

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

[source,python]
----
# プロトタイプ
hook = weechat.hook_hsignal(signal, callback, callback_data)

# 例
def my_hsignal_cb(data, signal, hashtable):
    # ...
    return weechat.WEECHAT_RC_OK

hook = weechat.hook_hsignal("test", "my_hsignal_cb", "")
----

==== hook_hsignal_send

_WeeChat バージョン 0.3.4 以上で利用可、バージョン 1.0 で更新。_

hsignal (ハッシュテーブルを持つシグナル) を送信。

プロトタイプ:

[source,C]
----
int weechat_hook_hsignal_send (const char *signal, struct t_hashtable *hashtable);
----

引数:

* 'signal': 送信するシグナル
* 'hashtable': ハッシュテーブル

戻り値 _(WeeChat バージョン 1.0 以上で利用可。)_:

* 最後に実行したコールバックの戻り値
  (コールバックを実行しなかった場合は 'WEECHAT_RC_OK'):
** 'WEECHAT_RC_OK'
** 'WEECHAT_RC_OK_EAT'
** 'WEECHAT_RC_ERROR'

C 言語での使用例:

[source,C]
----
int rc;
struct t_hashtable *hashtable = weechat_hashtable_new (8,
                                                       WEECHAT_HASHTABLE_STRING,
                                                       WEECHAT_HASHTABLE_STRING,
                                                       NULL,
                                                       NULL);
if (hashtable)
{
    weechat_hashtable_set (hashtable, "key", "value");
    rc = weechat_hook_hsignal_send ("my_hsignal", hashtable);
    weechat_hashtable_free (hashtable);
}
----

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

[source,python]
----
# プロトタイプ
rc = weechat.hook_hsignal_send(signal, hashtable)

# 例
rc = weechat.hook_hsignal_send("my_hsignal", {"key": "value"})
----

[[hsignal_irc_redirect_command]]
===== Hsignal irc_redirect_command

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

hsignal "irc_redirect_command" は irc
コマンドの出力をコールバックに転送するためのものです。

引数は以下のエントリを持つハッシュテーブル (キーと値は文字列) です:

* 'server': 内部サーバ名 (必須)
* 'pattern': 転送パターン (必須)、デフォルトパターン (irc プラグインが定義したもの)
  またはユーザ定義パターン (<<hsignal_irc_redirect_pattern>> を参照)
  のどちらか一方、デフォルトパターンは以下:
** 'ison'
** 'list'
** 'mode_channel'
** 'mode_channel_ban' ("mode #channel b")
** 'mode_channel_ban_exception' ("mode #channel e")
** 'mode_channel_invite' ("mode #channel I")
** 'mode_user'
** 'monitor'
** 'names'
** 'ping'
** 'time'
** 'topic'
** 'userhost'
** 'who'
** 'whois'
** 'whowas'
* 'signal': シグナル名 (必須)
* 'count': 転送を行う回数 (任意、デフォルトは 1 回)
* 'string': 受信する irc メッセージに含まれる文字列
  (任意ですが推奨します、この文字列を含むメッセージだけを転送します)
* 'timeout': 転送のタイムアウト、秒単位 (任意、デフォルトは 60)
* 'cmd_filter': フィルタする irc コマンドのコンマ区切りリスト
  (これらのコマンドはコールバックに送信されます、これ以外のコマンドは無視されます) (任意)

この hsignal を送信したら必ずその直後に irc
サーバにコマンドを送信してください、そうすれば送信したコマンドに対する応答が転送されます。

コマンドに対する応答を完全に受信したら、hsignal が送信されます。この
hsignal は 'irc_redirection_xxx_yyy' という名前で、ここで 'xxx' は
'signal' 、'yyy' は 'pattern' で指定したものになります。

以下の内容からなるハッシュテーブルが hsignal で送信されます (キーと値は文字列):

* 'output': コマンドの出力 (メッセージは "\n" で区切られています)
* 'output_size': 'output' のバイト数 (文字列)
* 'error': エラー文字列 (エラーが起きた場合):
** 'timeout': タイムアウトで転送を中止
* 'server': 内部サーバ名
* 'pattern': 転送パターン
* 'signal': シグナル名
* 'command': リダイレクトされたコマンド

C 言語での使用例:

[source,C]
----
int
test_whois_cb (void *data, const char *signal, struct t_hashtable *hashtable)
{
    weechat_printf (NULL, "error = %s", weechat_hashtable_get (hashtable, "error"));
    weechat_printf (NULL, "output = %s", weechat_hashtable_get (hashtable, "output"));
    return WEECHAT_RC_OK;
}

weechat_hook_hsignal ("irc_redirection_test_whois", &test_whois_cb, NULL);
struct t_hashtable *hashtable = weechat_hashtable_new (8,
                                                       WEECHAT_HASHTABLE_STRING,
                                                       WEECHAT_HASHTABLE_STRING,
                                                       NULL,
                                                       NULL);
if (hashtable)
{
    weechat_hashtable_set (hashtable, "server", "freenode");
    weechat_hashtable_set (hashtable, "pattern", "whois");
    weechat_hashtable_set (hashtable, "signal", "test");
    weechat_hashtable_set (hashtable, "string", "FlashCode");
    weechat_hook_hsignal_send ("irc_redirect_command", hashtable);
    weechat_hook_signal_send ("irc_input_send", WEECHAT_HOOK_SIGNAL_STRING,
                              "freenode;;2;;/whois FlashCode");
    weechat_hashtable_free (hashtable);
}
----

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

[source,python]
----
def test_whois_cb(data, signal, hashtable):
    weechat.prnt("", "error = %s" % hashtable["error"])
    weechat.prnt("", "output = %s" % hashtable["output"])
    return weechat.WEECHAT_RC_OK

weechat.hook_hsignal ("irc_redirection_test_whois", "test_whois_cb", "")
weechat.hook_hsignal_send("irc_redirect_command",
                          {"server": "freenode", "pattern": "whois", "signal": "test",
                           "string": "FlashCode"})
weechat.hook_signal_send("irc_input_send", weechat.WEECHAT_HOOK_SIGNAL_STRING,
                         "freenode;;2;;/whois FlashCode")
----

[[hsignal_irc_redirect_pattern]]
===== Hsignal irc_redirect_pattern

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

hsignal "irc_redirect_pattern" は irc 転送用のパターンを作成するために送信します
(<<hsignal_irc_redirect_command>> を参照)。

引数は以下のエントリを持つハッシュテーブルです (キーと値は文字列):

* 'pattern': パターンの名前 (必須)
* 'timeout': パターンのデフォルトタイムアウト、秒単位 (任意、デフォルトは 60)
* 'cmd_start': 転送を開始するコマンドのコンマ区切りリスト (任意)
* 'cmd_stop': 転送を終了するコマンドのコンマ区切りリスト (必須)
* 'cmd_extra': コマンドを停止した後に受信する可能性のあるコマンドのコンマ区切りリスト
  (任意)

'cmd_start'、'cmd_stop'、'cmd_extra'
には受け取ったメッセージに必ず含まれていなければいけない
"string" の位置を示す整数を与えることが可能、例:

----
352:1,354,401:1
----

コマンド 352 と 401 の応答は最初の受信メッセージの第
1 引数に "string" が含まれていなければいけません。

[IMPORTANT]
パターンは転送で使われた後に破棄されます、
複数回の転送でパターンを必要な場合は、転送前に毎回必ずパターンを作ってください。

C 言語での使用例:

[source,C]
----
struct t_hashtable *hashtable = weechat_hashtable_new (8,
                                                       WEECHAT_HASHTABLE_STRING,
                                                       WEECHAT_HASHTABLE_STRING,
                                                       NULL,
                                                       NULL);
if (hashtable)
{
    weechat_hashtable_set (hashtable, "pattern", "my_whois");
    weechat_hashtable_set (hashtable, "timeout", "30");
    weechat_hashtable_set (hashtable, "cmd_start", "311:1");
    weechat_hashtable_set (hashtable, "cmd_stop", "318:1,401:1,402:1,431:1,461");
    weechat_hashtable_set (hashtable, "cmd_extra", "318:1");
    weechat_hook_hsignal_send ("irc_redirect_pattern", hashtable);
    /*
     * now redirect irc whois command with hsignal irc_redirect_command,
     * using pattern "my_whois"
     */
    /* ... */
    weechat_hashtable_free (hashtable);
}
----

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

[source,python]
----
weechat.hook_hsignal_send("irc_redirect_pattern",
                          {"pattern": "my_whois", "timeout": "30",
                           "cmd_start": "311:1",
                           "cmd_stop": "318:1,401:1,402:1,431:1,461",
                           "cmd_extra": "318:1"})
# now redirect irc whois command with hsignal irc_redirect_command
# using pattern "my_whois"
# ...
----

==== hook_config

設定オプションをフック。

プロトタイプ:

[source,C]
----
struct t_hook *weechat_hook_config (const char *option,
                                    int (*callback)(void *data,
                                                    const char *option,
                                                    const char *value),
                                    void *callback_data);
----

引数:

* 'option': オプション、フォーマットは完全な名前、コマンド `/set` で使うのと同じ
  (例: `weechat.look.item_time_format`)、ワイルドカード "*" を使うことができます
  (優先度の設定が可能、<<hook_priority,優先度>>に関する注意を参照)
* 'callback':
  設定オプションが変更されたら呼び出す関数、引数と戻り値:
** 'void *data': ポインタ
** 'const char *option': オプションの名前
** 'const char *value': オプションの新しい値
** 戻り値:
*** 'WEECHAT_RC_OK'
*** 'WEECHAT_RC_ERROR'
* 'callback_data': WeeChat がコールバックを呼び出す際にコールバックに渡すポインタ

戻り値:

* 新しいフックへのポインタ、エラーが起きた場合は NULL

C 言語での使用例:

[source,C]
----
int
my_config_cb (void *data, const char *option, const char *value)
{
    /* ... */
    return WEECHAT_RC_OK;
}

/* catch changes to option "weechat.look.item_time_format" */
struct t_hook *my_config_hook = weechat_hook_config ("weechat.look.item_time_format",
                                                     &my_config_cb, NULL);
----

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

[source,python]
----
# プロトタイプ
hook = weechat.hook_config(option, callback, callback_data)

# 例
def my_config_cb(data, option, value):
    # ...
    return weechat.WEECHAT_RC_OK

# catch changes to option "weechat.look.item_time_format"
hook = weechat.hook_config("weechat.look.item_time_format", "my_config_cb", "")
----

==== hook_completion

補完をフック。

プロトタイプ:

[source,C]
----
struct t_hook *weechat_hook_completion (const char *completion_item,
                                        const char *description,
                                        int (*callback)(void *data,
                                                        const char *completion_item,
                                                        struct t_gui_buffer *buffer,
                                                        struct t_gui_completion *completion),
                                        void *callback_data);
----

引数:

* 'completion_item': 補完要素の名前、この後フックされたコマンドで
  '%(name)' を使うことができます ('completion' 引数)
  (優先度の設定が可能、<<hook_priority,優先度>>に関する注意を参照)
* 'description': 補完の説明
* 'callback': 補完要素 (ユーザはこの要素を使って何かを補完している)
  が使われた場合に呼び出す関数、引数と戻り値:
** 'void *data': ポインタ
** 'const char *completion_item': 補完要素の名前
** 'struct t_gui_buffer *buffer': 補完が行われたバッファ
** 'struct t_gui_completion *completion':
   補完に際して単語を追加するために使われる構造体
   (<<_hook_completion_list_add,weechat_hook_completion_list_add>> を参照)
** 戻り値:
*** 'WEECHAT_RC_OK'
*** 'WEECHAT_RC_ERROR'
* 'callback_data': WeeChat がコールバックを呼び出す際にコールバックに渡すポインタ

[NOTE]
補完名はグローバルです (WeeChat
とプラグインで共有されます)。このため、"plugin_xxx" (ここで "xxx" は要素の名前)
などの一意的なプレフィックスをつけた名前を使うことをおすすめします。

[IMPORTANT]
コールバックは
<<_hook_completion_list_add,weechat_hook_completion_list_add>>
関数を呼び出すだけで、コマンドラインをコールバックで絶対に*変更しない*でください。 +
key[Tab] が押された時にコマンドラインを更新するためには、関数
<<_hook_command_run,weechat_hook_command_run>> を使ってコマンド
"/input complete_next" をフックしてください (コールバックがコマンドラインを更新する場合は必ず
'WEECHAT_RC_OK_EAT' を返してください。そうすれば WeeChat は補完を行いません)。

戻り値:

* 新しいフックへのポインタ、エラーが起きた場合は NULL

C 言語での使用例:

[source,C]
----
int
my_completion_cb (void *data, const char *completion_item,
                  struct t_gui_buffer *buffer,
                  struct t_gui_completion *completion)
{
    weechat_hook_completion_list_add (completion, "word1",
                                      0, WEECHAT_LIST_POS_SORT);
    weechat_hook_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);
----

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

[source,python]
----
# プロトタイプ
hook = weechat.hook_completion(completion_item, description, callback, callback_data)

# 例
def my_completion_cb(data, completion_item, buffer, completion):
    weechat.hook_completion_list_add(completion, "word1", 0, weechat.WEECHAT_LIST_POS_SORT)
    weechat.hook_completion_list_add(completion, "test_word2", 0, weechat.WEECHAT_LIST_POS_SORT)
    return weechat.WEECHAT_RC_OK

hook = weechat.hook_completion("plugin_item", "my custom completion!",
                               "my_completion_cb", "")
----

==== hook_completion_get_string

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

補完プロパティを文字列で取得。

プロトタイプ:

[source,C]
----
const char *weechat_hook_completion_get_string (struct t_gui_completion *completion,
                                                const char *property);
----

引数:

* 'completion': 補完へのポインタ
* 'property': プロパティ名:
** 'base_command': 補完に使ったコマンド
** 'base_word': 補完された単語
** 'args': コマンド引数 (元の単語を含む)

C 言語での使用例:

[source,C]
----
int
my_completion_cb (void *data, const char *completion_item,
                  struct t_gui_buffer *buffer,
                  struct t_gui_completion *completion)
{
    /* get arguments of command */
    const char *args = weechat_hook_completion_get_string (completion, "args");

    /* completion depending on args */
    /* ... */

    return WEECHAT_RC_OK;
}
----

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

[source,python]
----
# プロトタイプ
value = weechat.hook_completion_get_string(completion, property)

# 例
def my_completion_cb(data, completion_item, buffer, completion):
    # get arguments of command
    args = weechat.hook_completion_get_string(completion, "args")
    # completion depending on args
    # ...
    return weechat.WEECHAT_RC_OK
----

==== hook_completion_list_add

補完用に単語を追加。

プロトタイプ:

[source,C]
----
void weechat_hook_completion_list_add (struct t_gui_completion *completion,
                                       const char *word,
                                       int nick_completion,
                                       const char *where);
----

引数:

* 'completion': 補完へのポインタ
* 'word': 追加する単語
* 'nick_completion': 単語がニックネームの場合は 1、そうでなければ 0
* 'where': 単語を追加するリスト上での位置:
** 'WEECHAT_LIST_POS_SORT': リストがソートされた状態になるような位置
** 'WEECHAT_LIST_POS_BEGINNING': リストの最初
** 'WEECHAT_LIST_POS_END': リストの最後

C 言語での使用例: <<_hook_completion,weechat_hook_completion>> を参照。

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

[source,python]
----
# プロトタイプ
weechat.hook_completion_list_add(completion, word, nick_completion, where)

# 例: 前の hook_completion 関数を参照
----

==== hook_modifier

修飾子をフック。

プロトタイプ:

[source,C]
----
struct t_hook *weechat_hook_modifier (const char *modifier,
                                      char *(*callback)(void *data,
                                                        const char *modifier,
                                                        const char *modifier_data,
                                                        const char *string),
                                      void *callback_data);
----

引数:

* 'modifier': 修飾子名、Weechat またはプラグインが使う修飾子のリスト
  (優先度の設定が可能、<<hook_priority,優先度>>に関する注意を参照)
  (以下の表を参照)
* 'callback': 修飾子が使われた際に呼び出す関数、引数と戻り値:
** 'void *data': ポインタ
** 'const char *modifier': 修飾子の名前
** 'const char *modifier_data': 修飾子に渡すデータ
** 'const char *string': 修飾子に渡す文字列
** 戻り値: 新しい文字列
* 'callback_data': WeeChat がコールバックを呼び出す際にコールバックに渡すポインタ

戻り値:

* 新しいフックへのポインタ、エラーが起きた場合は NULL

WeeChat とプラグインが使う修飾子のリスト:

[width="100%",cols="^2,3,4,4",options="header"]
|===
| 修飾子 | 修飾子データ | 文字列 | 出力

| charset_decode |
  plugin.buffer_name |
  任意の文字列 |
  プラグインおよびバッファの文字セットから UTF-8 にデコードされた文字列

| charset_encode |
  plugin.buffer_name |
  任意の文字列 |
  UTF-8 からプラグインおよびバッファの文字セットにエンコードされた文字列

| irc_color_decode |
  色を保持する場合は "1"、削除する場合は "0" |
  任意の文字列 |
  WeeChat 色コードに変換された IRC 色コードを含む (または IRC 色コードを削除された) 文字列

| irc_color_encode |
  色を保持する場合は "1"、削除する場合は "0" |
  任意の文字列 |
  IRC 色コードを含む (または IRC 色コードを削除された) 文字列

| irc_color_decode_ansi +
  _(WeeChat バージョン 1.0 以上で利用可)_ |
  色を保持する場合は "1"、削除する場合は "0" |
  任意の文字列 |
  IRC 色コードに変換された ANSI 色コードを含む (または ANSI 色コードを削除された) 文字列

| irc_command_auth +
  _(WeeChat バージョン 0.4.1 以上で利用可)_ |
  サーバ名 |
  認証コマンド (例: `/msg nickserv identify password`) |
  パスワードを隠したコマンド (例: `/msg nickserv identify ********`)

| irc_message_auth +
  _(WeeChat バージョン 0.4.1 以上で利用可)_ |
  サーバ名 |
  `/msg` をサーバに送信した後に表示されるメッセージ |
  パスワードを隠したメッセージ

| irc_in_xxx ^(1)^ |
  サーバ名 |
  IRC サーバから受信したメッセージの内容 (文字セットをデコードする前) |
  メッセージの新しい内容

| irc_in2_xxx ^(1)^ +
  _(WeeChat バージョン 0.3.5 以上で利用可)_ |
  サーバ名 |
  IRC サーバから受信したメッセージの内容 (文字セットをデコードした後) |
  メッセージの新しい内容

| irc_out1_xxx ^(1)^ +
  _(WeeChat バージョン 0.3.7 以上で利用可)_ |
  サーバ名 |
  IRC サーバに送信するメッセージの内容 (512 バイトを超えないように自動分割する前) |
  メッセージの新しい内容

| irc_out_xxx ^(1)^ |
  サーバ名 |
  IRC サーバに送信するメッセージの内容 (512 バイトを超えないように自動分割した後) |
  メッセージの新しい内容

| color_decode_ansi +
  _(WeeChat バージョン 1.0 以上で利用可)_ |
  色を保持する場合は "1"、削除する場合は "0" |
  任意の文字列 |
  WeeChat 色コードに変換された ANSI 色コードを含む (または ANSI 色コードを削除された) 文字列

| bar_condition_yyy ^(2)^ |
  ウィンドウへのポインタの文字列 ("0x123..") |
  空文字列 |
  バーを表示する場合は "1"、隠す場合は "0"

| history_add +
  _(WeeChat バージョン 0.3.2 以上で利用可)_ |
  バッファへのポインタの文字列 ("0x123..") |
  コマンド履歴に追加するコマンドラインの内容 (バッファとグローバル履歴) |
  コマンド履歴に追加した文字列

| input_text_content |
  バッファへのポインタの文字列 ("0x123..") |
  コマンドラインの内容 |
  コマンドラインの新しい内容

| input_text_display |
  バッファへのポインタの文字列 ("0x123..") |
  カーソルタグを含まないコマンドラインの内容 |
  新しい文字列、表示のみ (コマンドラインは変化しない)

| input_text_display_with_cursor |
  バッファへのポインタの文字列 ("0x123..") |
  カーソルタグを含むコマンドラインの内容 |
  新しい文字列、表示のみ (コマンドラインは変化しない)

| input_text_for_buffer +
  _(WeeChat バージョン 0.3.7 以上で利用可)_ |
  バッファへのポインタの文字列 ("0x123..") |
  バッファに送信するコマンドラインの内容 (テキストまたはコマンド) |
  バッファに送信するコマンドラインの新しい内容

| weechat_print |
  plugin + ";" + buffer_name + ";" + tags |
  表示されたメッセージ |
  表示される新しいメッセージ
|===

[NOTE]
^(1)^ 'xxx' は IRC コマンド名。 +
^(2)^ 'yyy' はバーの名前。

C 言語での使用例:

[source,C]
----
char *
my_modifier_cb (void *data, const char *modifier,
                const char *modifier_data,
                const char *string)
{
    char *result;
    int length;

    if (!string)
        return NULL;

    length = strlen (string) + 5;
    result = malloc (length);
    if (result)
    {
        /* add "xxx" to any message printed */
        snprintf (result, length, "%s xxx", string);
    }

    return result;
}

struct t_hook *my_modifier_hook = weechat_hook_modifier ("weechat_print",
                                                         &my_modifier_cb, NULL);
----

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

[source,python]
----
# プロトタイプ
hook = weechat.hook_modifier(modifier, callback, callback_data)

# 例
def my_modifier_cb(data, modifier, modifier_data, string):
    return "%s xxx" % string

hook = weechat.hook_modifier("weechat_print", "my_modifier_cb", "")
----

==== hook_modifier_exec

修飾子を実行。

プロトタイプ:

[source,C]
----
char *weechat_hook_modifier_exec (const char *modifier,
                                  const char *modifier_data,
                                  const char *string);
----

引数:

* 'modifier': 修飾子の名前
* 'modifier_data': 修飾子に渡すデータ
* 'string': 修正する文字列

戻り値:

* 修正された文字列、エラーが起きた場合は NULL

C 言語での使用例:

[source,C]
----
char *new_string = weechat_hook_modifier_exec ("my_modifier",
                                               my_data, my_string);
----

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

[source,python]
----
# プロトタイプ
weechat.hook_modifier_exec(modifier, modifier_data, string)

# 例
weechat.hook_modifier_exec("my_modifier", my_data, my_string)
----

==== hook_info

情報をフック (コールバックを呼び出し、文字列を返す)。

プロトタイプ:

[source,C]
----
struct t_hook *weechat_hook_info (const char *info_name,
                                  const char *description,
                                  const char *args_description,
                                  const char *(*callback)(void *data,
                                                          const char *info_name,
                                                          const char *arguments),
                                  void *callback_data);
----

引数:

* 'info_name': 情報の名前
  (優先度の設定が可能、<<hook_priority,優先度>>に関する注意を参照)
* 'description': 説明
* 'args_description': 引数の説明 (任意、NULL にすることも可)
* 'callback': 情報が要求されたら呼び出す関数、引数と戻り値:
** 'void *data': ポインタ
** 'const char *info_name': 情報の名前
** 'const char *arguments': 追加の引数、情報に依存
** 戻り値: 要求された情報の値
* 'callback_data': WeeChat がコールバックを呼び出す際にコールバックに渡すポインタ

戻り値:

* 新しいフックへのポインタ、エラーが起きた場合は NULL

C 言語での使用例:

[source,C]
----
const char *
my_info_cb (void *data, const char *info_name, const char *arguments)
{
    /* ... */
    return pointer_to_string;
}

/* add info "my_info" */
struct t_hook *my_info_hook = weechat_hook_info ("my_info",
                                                 "Some info",
                                                 "Info about arguments",
                                                 &my_info_cb, NULL);
----

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

[source,python]
----
# プロトタイプ
hook = weechat.hook_info(info_name, description, args_description, callback, callback_data)

# 例
def my_info_cb(data, info_name, arguments):
    return "some_info"

hook = weechat.hook_info("my_info", "Some info", "Info about arguments",
                         "my_info_cb", "")
----

==== hook_info_hashtable

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

情報をフック (コールバックを呼び出し、ハッシュテーブルを返す)。

プロトタイプ:

[source,C]
----
struct t_hook *weechat_hook_info_hashtable (const char *info_name,
                                            const char *description,
                                            const char *args_description,
                                            const char *output_description,
                                            struct t_hashtable *(*callback)(void *data,
                                                                            const char *info_name,
                                                                            struct t_hashtable *hashtable),
                                            void *callback_data);
----

引数:

* 'info_name': 情報の名前
  (優先度の設定が可能、<<hook_priority,優先度>>に関する注意を参照)
* 'description': 説明
* 'args_description': 引数ハッシュテーブルの説明 (任意、NULL でも可)
* 'output_description': コールバックが返すハッシュテーブルの説明
  (任意、NULL でも可)
* 'callback': 情報を要求する際に呼び出す関数、引数と戻り値:
** 'void *data': ポインタ
** 'const char *info_name': 情報の名前
** 'struct t_hashtable *hashtable': ハッシュテーブル、情報に依存
** 戻り値: 要求したハッシュテーブル
* 'callback_data': WeeChat がコールバックを呼び出す際にコールバックに渡すポインタ

戻り値:

* 新しいフックへのポインタ、エラーが起きた場合は NULL

C 言語での使用例:

[source,C]
----
struct t_hashtable *
my_info_hashtable_cb (void *data, const char *info_name, struct t_hashtable *hashtable)
{
    /* ... */
    return pointer_to_new_hashtable;
}

/* add info "my_info_hashtable" */
struct t_hook *my_info_hook = weechat_hook_info_hashtable ("my_info_hashtable",
                                                           "Some info",
                                                           "Info about input hashtable",
                                                           "Info about output hashtable",
                                                           &my_info_hashtable_cb, NULL);
----

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

[source,python]
----
# プロトタイプ
hook = weechat.hook_info_hashtable(info_name, description, args_description,
                                   output_description, callback, callback_data)

# 例
def my_info_hashtable_cb(data, info_name, hashtable):
    return {"test_key": "test_value"}

hook = weechat.hook_info_hashtable("my_info_hashtable", "Some info",
                                   "Info about input hashtable",
                                   "Info about output hashtable",
                                   "my_info_hashtable_cb", "")
----

==== hook_infolist

インフォリストをフック: コールバックは要求したインフォリストへのポインタを返す。

プロトタイプ:

[source,C]
----
struct t_hook *weechat_hook_infolist (const char *infolist_name,
                                      const char *description,
                                      const char *pointer_description,
                                      const char *args_description,
                                      struct t_infolist *(*callback)(void *data,
                                                                     const char *infolist_name,
                                                                     void *pointer,
                                                                     const char *arguments),
                                      void *callback_data);
----

引数:

* 'infolist_name': インフォリストの名前
  (優先度の設定が可能、<<hook_priority,優先度>>に関する注意を参照)
* 'description': 説明
* 'pointer_description': ポインタの説明 (任意、NULL でも可)
* 'args_description': 引数の説明 (任意、NULL でも可)
* 'callback':
  インフォリストが要求された際に呼び出すコールバック、引数と戻り値:
** 'void *data': ポインタ
** 'const char *infolist_name': インフォリストの名前
** 'void *pointer': インフォリストが返すオブジェクトへのポインタ
   (インフォリストの要素を 1 つだけ返す)
** 'const char *arguments': 追加の引数、インフォリストに依存
** 戻り値: 要求したインフォリスト
* 'callback_data': WeeChat がコールバックを呼び出す際にコールバックに渡すポインタ

戻り値:

* 新しいフックへのポインタ、エラーが起きた場合は NULL

C 言語での使用例:

[source,C]
----
struct t_infolist *
my_infolist_cb (void *data, const char *infolist_name, void *pointer,
                const char *arguments)
{
    struct t_infolist *my_infolist;

    /* build infolist */
    /* ... */

    return my_infolist;
}

/* add infolist "my_infolist" */
struct t_hook *my_infolist = weechat_hook_infolist ("my_infolist",
                                                    "Infolist with some data",
                                                    "Info about pointer",
                                                    "Info about arguments",
                                                    &my_infolist_cb, NULL);
----

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

[source,python]
----
# プロトタイプ
hook = weechat.hook_infolist(infolist_name, description, pointer_description,
                             args_description, callback, callback_data)

# 例
def my_infolist_cb(data, infolist_name, pointer, arguments):
    # build infolist
    # ...
    return my_infolist

hook = weechat.hook_infolist("my_infolist", "Infolist with some data",
                             "Info about pointer", "Info about arguments",
                             "my_infolist_cb", "")
----

==== hook_hdata

hdata をフック: コールバックは要求した hdata へのポインタを返す。

プロトタイプ:

[source,C]
----
struct t_hook *weechat_hook_hdata (const char *hdata_name,
                                   const char *description,
                                   struct t_hdata *(*callback)(void *data,
                                                               const char *hdata_name),
                                   void *callback_data);
----

引数:

* 'hdata_name': hdata の名前
  (優先度の設定が可能、<<hook_priority,優先度>>に関する注意を参照)
* 'description': 説明
* 'callback':
  hdata が要求された際に呼び出す関数、引数と戻り値:
** 'void *data': ポインタ
** 'const char *hdata_name': hdata の名前
** 戻り値: 要求された hdata
* 'callback_data': WeeChat がコールバックを呼び出す際にコールバックに渡すポインタ

戻り値:

* 新しいフックへのポインタ、エラーが起きた場合は NULL

C 言語での使用例:

[source,C]
----
struct t_hdata *
my_hdata_cb (void *data, const char *hdata_name)
{
    struct t_hdata *my_hdata;

    /* build hdata */
    /* ... */

    return my_hdata;
}

/* add hdata "my_hdata" */
struct t_hook *my_hdata = weechat_hook_hdata ("my_hdata",
                                              "Hdata for my structure",
                                              &my_hdata_cb, NULL);
----

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

==== hook_focus

フォーカス (マウスイベントやカーソルモード
(カーソルが自由に移動出来る状態) でキーが押されたこと) をフック。

プロトタイプ:

[source,C]
----
struct t_hook *weechat_hook_focus (const char *area,
                                   struct t_hashtable *(*callback)(void *data,
                                                                   struct t_hashtable *info),
                                   void *callback_data);
----

引数:

* 'area': チャットエリアの場合は "chat"、またはバー要素の名前
  (優先度の設定が可能、<<hook_priority,優先度>>に関する注意を参照)
* 'callback':
  フォーカスが当たったら呼び出す関数、引数と戻り値:
** 'void *data': ポインタ
** 'struct t_hashtable *info': フォーカスの情報を含むハッシュテーブルと、他の
   (より高い優先度を持つ) フォーカスコールバックを呼び出して返された文字列 (以下のテーブルを参照)
** 戻り値: "info" ポインタ (完全なハッシュテーブル)
   または新しいハッシュテーブル (コールバックが作成、キーと値は
   "string" 型) へのポインタ、この新しいハッシュテーブルの内容は
   'info' に追加され、他のフォーカスコールバックに渡されます
* 'callback_data': WeeChat がコールバックを呼び出す際にコールバックに渡すポインタ

[IMPORTANT]
マウスジェスチャの場合、コールバックを 2 回呼び出します: 1
回目はボタンが押された時 (この時のエリアはジェスチャ対象のエリアです)、2
回目はボタンが離された時 (この時のエリアはマスジェスチャを開始したエリアとは異なる場合があります):
このため、必ず*毎回* コールバックをテストして、ハッシュテーブルに含まれる
info を使う前にエリアが一致していることを確認して下さい。

コールバックに送られるハッシュテーブルの内容 (キーと値は "string" 型):

[width="100%",cols="5m,5,8,3",options="header"]
|===
| キー ^(1)^ | 説明 | 値の例 | 定義できない場合の値

| _x | スクリーン上での列座標 |
  "0" ... "n" |

| _y | スクリーン上での行座標 |
  "0" ... "n" |

| _key | キーまたはマウスイベント |
  "button1"、"button2-gesture-left"、... |

| _window | ウィンドウへのポインタ |
  "0x12345678" | ""

| _window_number | ウィンドウの番号 |
  "1" ... "n" | "*"

| _buffer | バッファへのポインタ |
  "0x12345678" | ""

| _buffer_number | バッファの番号 |
  "1" ... "n" | "-1"

| _buffer_plugin | バッファのプラグイン名 |
  "core"、"irc"、... | ""

| _buffer_name | バッファの名前 |
  "weechat"、"freenode.#weechat"、... | ""

| _buffer_full_name | バッファの完全な名前 |
  "core.weechat"、"irc.freenode.#weechat"、... | ""

| _buffer_localvar_XXX ^(2)^ | バッファのローカル変数 |
  任意の値 | 未定義

| _chat | チャットエリアインジケータ |
  "0" または "1" | "0"

| _chat_line | 行へのポインタ +
  _(WeeChat バージョン 1.2 以上で利用可)_ |
  "0x12345678" | ""

| _chat_line_x | 行中の列番号 ^(3)^ |
  "0" ... "n" | "-1"

| _chat_line_y | 行番号 ^(3)^ |
  "0" ... "n" | "-1"

| _chat_line_date | 日付/時間の行 |
  "1313237175" | "0"

| _chat_line_date_printed | 日付/時間の行 ^(4)^ |
  "1313237175" | "0"

| _chat_line_time | 表示された時間 |
  "14:06:15" | ""

| _chat_line_tags | 行に設定されたタグ |
  "irc_privmsg,nick_flashy,log1" | ""

| _chat_line_nick | 行を発言したニックネーム |
  "FlashCode" | ""

| _chat_line_prefix | 行のプレフィックス |
  "@FlashCode" | ""

| _chat_line_message | 行のメッセージ部分 |
  "Hello world!" | ""

| _chat_word | (x,y) の位置にある単語 |
  "Hello" | ""

| _chat_bol | 行頭から (x-1,y) まで |
  "He" | ""

| _chat_eol | (x,y) から行末まで |
  "llo world!" | ""

| _bar_name | バーの名前 |
  "title"、"nicklist"、... | ""

| _bar_filling | バーのフィリング |
  "horizontal"、"vertical"、... | ""

| _bar_item_name | バー要素の名前 |
  "buffer_nicklist"、"hotlist"、... | ""

| _bar_item_line | バー要素中の行座標 |
  "0" ... "n" | "-1"

| _bar_item_col | バー要素中の列座標 |
  "0" ... "n" | "-1"
|===

[NOTE]
^(1)^ "2" を後ろにつけたキー (例: "_x2"、"_y2"、"_window2"、...)
には 2 番目の位置に関する情報が収められています
(この値に意味があるマウスジェスチャの時だけで、マウスボタンの離された位置に関する情報が収められています)。 +
^(2)^ `XXX` はバッファのローカル変数の名前です。 +
^(3)^ これは自由内容のバッファで定義されています。 +
^(4)^ WeeChat がバッファに行を追加した日付です
("_chat_line_date" よりも大きいか同じ)。

バー要素 "buffer_nicklist" の追加情報:

[width="70%",cols="3m,3,8",options="header"]
|===
| キー           | プラグイン ^(1)^ | 説明
| nick           | core         | ニックネーム
| prefix         | core         | ニックネームのプレフィックス
| group          | core         | グループ名
| irc_host       | irc          | ニックネームのホスト名 (判る場合)
|===

[NOTE]
^(1)^ プラグインの名前は hook_focus
がどのバー要素に関する情報を渡したかを意味しています (したがって、例えばプラグインが
"irc" の場合、ハッシュテーブル info の内容は irc バッファに関するものになります)。

戻り値:

* 新しいフックへのポインタ、エラーが起きた場合は NULL

C 言語での使用例:

[source,C]
----
struct t_hashtable *
my_focus_nicklist_cb (void *data, struct t_hashtable *info)
{
    /* add strings in hashtable */
    /* ... */

    return info;
}

/* add focus on nicklist */
struct t_hook *my_focus = weechat_hook_focus ("buffer_nicklist",
                                              &my_focus_nicklist_cb, NULL);
----

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

[source,python]
----
# プロトタイプ
hook = weechat.hook_focus(area, callback, callback_data)

# 例
def my_focus_nicklist_cb(data, info):
    # build dict
    # ...
    return my_dict

hook = weechat.hook_focus("buffer_nicklist", "my_focus_nicklist_cb", "")
----

==== hook_set

_WeeChat バージョン 0.3.9 以上で利用可 (スクリプト: WeeChat バージョン 0.4.3 以上で利用可)。_

フックプロパティの文字列値を設定。

プロトタイプ:

[source,C]
----
void weechat_hook_set (struct t_hook *hook, const char *property,
                       const char *value);
----

引数:

* 'hook': "weechat_hook_xxx()" の戻り値
* 'property': プロパティ名 (以下の表を参照)
* 'value': プロパティの新しい値

プロパティ:

[width="100%",cols="^2,2,2,5",options="header"]
|===
| 名前 | フック型 | 値 | 説明

| subplugin | 任意の型 | 任意の文字列 |
  サブプラグインの名前 (通常は `/help command` で 'command'
  をタイプした時のフックで表示されるスクリプト名)

| stdin +
  _(WeeChat バージョン 0.4.3 以上で利用可)_ |
  'process' 、'process_hashtable' | 任意の文字列 |
  子プロセスの標準入力 ('stdin') にデータを送信

| stdin_close +
  _(WeeChat バージョン 0.4.3 以上で利用可)_ |
  'process' 、'process_hashtable' | (非使用) |
  子プロセスの標準入力 ('stdin') にデータを送信するパイプを閉じる

| signal +
  _(WeeChat バージョン 1.0 以上で利用可)_ |
  'process'、'process_hashtable' |
  シグナル番号または以下の名前から 1 つ:
  `hup`、`int`、`quit`、`kill`、`term`、`usr1`、`usr2` |
  子プロセスにシグナルを送信
|===

C 言語での使用例:

[source,C]
----
struct t_hook *my_command_hook =
    weechat_hook_command ("abcd", "description",
                          "args", "description args",
                          "", &my_command_cb, NULL);
weechat_hook_set (my_command_hook, "subplugin", "test");
----

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

[source,python]
----
# プロトタイプ
weechat.hook_set(hook, property, value)

# 例
def my_process_cb(data, command, return_code, out, err):
    # ...
    return weechat.WEECHAT_RC_OK

hook = weechat.hook_process_hashtable("/path/to/command", {"stdin": "1"},
                                      20000, "my_process_cb", "")
weechat.hook_set(hook, "stdin", "data sent to stdin of child process")
weechat.hook_set(hook, "stdin_close", "")  # optional
----

==== unhook

フックを解除。

プロトタイプ:

[source,C]
----
void weechat_unhook (struct t_hook *hook);
----

引数:

* 'hook': "weechat_hook_xxx()" の戻り値

C 言語での使用例:

[source,C]
----
struct t_hook *my_hook = weechat_hook_command ( /* ... */ );
/* ... */
weechat_unhook (my_hook);
----

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

[source,python]
----
# プロトタイプ
weechat.unhook(hook)

# 例
weechat.unhook(my_hook)
----

==== unhook_all

現在のプラグインで設定したフックをすべて解除。

プロトタイプ:

[source,C]
----
void weechat_unhook_all ();
----

C 言語での使用例:

[source,C]
----
weechat_unhook_all ();
----

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

[source,python]
----
# プロトタイプ
weechat.unhook_all()

# 例
weechat.unhook_all()
----

[[buffers]]
=== バッファ

バッファを作成/検索/閉じる関数

==== buffer_new

新しいバッファを開く。

プロトタイプ:

[source,C]
----
struct t_gui_buffer *weechat_buffer_new (const char *name,
                                         int (*input_callback)(void *data,
                                                               struct t_gui_buffer *buffer,
                                                               const char *input_data),
                                         void *input_callback_data,
                                         int (*close_callback)(void *data,
                                                               struct t_gui_buffer *buffer),
                                         void *close_callback_data);
----

引数:

* 'name': バッファの名前 (プラグインに対して固有)
* 'input_callback':
  入力テキストをバッファに挿入する際に呼び出す関数、引数と戻り値:
** 'void *data': ポインタ
** 'struct t_gui_buffer *buffer': バッファポインタ
** 'const char *input_data': 入力データ
** 戻り値:
*** 'WEECHAT_RC_OK'
*** 'WEECHAT_RC_ERROR'
* 'callback_data': WeeChat がコールバックを呼び出す際にコールバックに渡すポインタ
* 'close_callback':
  バッファを閉じる際に呼び出す関数、引数と戻り値:
** 'void *data': ポインタ
** 'struct t_gui_buffer *buffer': バッファポインタ
** 戻り値:
*** 'WEECHAT_RC_OK'
*** 'WEECHAT_RC_ERROR'
* 'callback_data': WeeChat がコールバックを呼び出す際にコールバックに渡すポインタ

戻り値:

* 新しいバッファへのポインタ、エラーが起きた場合は NULL

C 言語での使用例:

[source,C]
----
int
my_input_cb (void *data, struct t_gui_buffer *buffer, const char *input_data)
{
    weechat_printf (buffer, "Text: %s", input_data);
    return WEECHAT_RC_OK;
}

int
my_close_cb (void *data, struct t_gui_buffer *buffer)
{
    weechat_printf (NULL, "Buffer '%s' will be closed!",
                    weechat_buffer_get_string (buffer, "name"));
    return WEECHAT_RC_OK;
}

struct t_gui_buffer *my_buffer = weechat_buffer_new ("my_buffer",
                                                     &my_input_cb, NULL,
                                                     &my_close_cb, NULL);
----

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

[source,python]
----
# プロトタイプ
buffer = weechat.buffer_new(name, input_callback, input_callback_data,
    close_callback, close_callback_data)

# 例
def my_input_cb(data, buffer, input_data):
    weechat.prnt(buffer, "Text: %s" % input_data)
    return weechat.WEECHAT_RC_OK

def my_close_cb(data, buffer):
    weechat.prnt("", "Buffer '%s' will be closed!" % weechat.buffer_get_string(buffer, "name"))
    return weechat.WEECHAT_RC_OK

buffer = weechat.buffer_new("my_buffer", "my_input_cb", "", "my_close_cb", "")
----

==== current_buffer

現在のバッファへのポインタを返す (現在のウィンドウに表示されているバッファ)。

プロトタイプ:

[source,C]
----
struct t_gui_buffer *weechat_current_buffer ();
----

戻り値:

* 現在のバッファへのポインタ

C 言語での使用例:

[source,C]
----
weechat_printf (weechat_current_buffer (), "Text on current buffer");
----

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

[source,python]
----
# プロトタイプ
buffer = weechat.current_buffer()

# 例
weechat.prnt(weechat.current_buffer(), "Text on current buffer")
----

==== buffer_search

_バージョン 1.0 で更新。_

プラグインおよび名前でバッファを検索。

プロトタイプ:

[source,C]
----
struct t_gui_buffer *weechat_buffer_search (const char *plugin,
                                            const char *name);
----

引数:

* 'plugin': プラグインの名前、以下の特殊値を使うことができます:
** `==`: name 引数でバッファの完全な名前を使う (例:
   `freenode.#weechat` ではなく `irc.freenode.#weechat`)
   _(WeeChat バージョン 1.0 以上で利用可)_
* 'name': バッファの名前、NULL または空文字列の場合、現在のバッファ
  (現在のウィンドウに表示されているバッファ) を返す; 名前が `(?i)`
  で始まる場合、検索は大文字小文字を区別せずに検索 _(WeeChat バージョン 1.0 以上で利用可)_

戻り値:

* 見つかったバッファへのポインタ、見つからない場合 NULL

C 言語での使用例:

[source,C]
----
struct t_gui_buffer *buffer1 = weechat_buffer_search ("irc", "freenode.#weechat");
struct t_gui_buffer *buffer2 = weechat_buffer_search ("==", "irc.freenode.#test");  /* WeeChat ≥ 1.0 */
----

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

[source,python]
----
# プロトタイプ
buffer = weechat.buffer_search(plugin, name)

# 例
buffer = weechat.buffer_search("my_plugin", "my_buffer")
----

==== buffer_search_main

WeeChat メインバッファ ('core' バッファ、WeeChat
を実行して最初に表示されるバッファ) を検索。

プロトタイプ:

[source,C]
----
struct t_gui_buffer *weechat_buffer_search_main ();
----

戻り値:

* WeeChat メインバッファ ('core' バッファ) へのポインタ

C 言語での使用例:

[source,C]
----
struct t_gui_buffer *weechat_buffer = weechat_buffer_search_main ();
----

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

[source,python]
----
# プロトタイプ
buffer = weechat.buffer_search_main()

# 例
buffer = weechat.buffer_search_main()
----

==== buffer_clear

バッファの内容を消去。

プロトタイプ:

[source,C]
----
void weechat_buffer_clear (struct t_gui_buffer *buffer);
----

引数:

* 'buffer': バッファへのポインタ

C 言語での使用例:

[source,C]
----
struct t_gui_buffer *my_buffer = weechat_buffer_search ("my_plugin",
                                                        "my_buffer");
if (my_buffer)
{
    weechat_buffer_clear (my_buffer);
}
----

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

[source,python]
----
# プロトタイプ
weechat.buffer_clear(buffer)

# 例
buffer = weechat.buffer_search("my_plugin", "my_buffer")
if buffer != "":
    weechat.buffer_clear(buffer)
----

==== buffer_close

バッファを閉じる。

プロトタイプ:

[source,C]
----
void weechat_buffer_close (struct t_gui_buffer *buffer);
----

引数:

* 'buffer': バッファへのポインタ

C 言語での使用例:

[source,C]
----
struct t_gui_buffer *my_buffer = weechat_buffer_new ("my_buffer",
                                                     &my_input_cb, NULL,
                                                     &my_close_cb, NULL);
/* ... */
weechat_buffer_close (my_buffer);
----

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

[source,python]
----
# プロトタイプ
weechat.buffer_close(buffer)

# 例
buffer = weechat.buffer_new("my_buffer", "my_input_cb", "", "my_close_cb", "")
# ...
weechat.buffer_close(buffer)
----

==== buffer_merge

バッファを他のバッファにマージする:
両方のバッファは同じバッファ番号を持つ独立したバッファになり、WeeChat
は両方のバッファからの行を表示する (行は混合されます)。

プロトタイプ:

[source,C]
----
void weechat_buffer_merge (struct t_gui_buffer *buffer,
                           struct t_gui_buffer *target_buffer);
----

引数:

* 'buffer': バッファへのポインタ
* 'target_buffer': ターゲットバッファ、マージ先のバッファ

C 言語での使用例:

[source,C]
----
/* merge current buffer with weechat "core" buffer */
weechat_buffer_merge (weechat_current_buffer (),
                      weechat_buffer_search_main ());
----

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

[source,python]
----
# プロトタイプ
weechat.buffer_merge(buffer, target_buffer)

# 例
# merge current buffer with WeeChat "core" buffer
weechat.buffer_merge(weechat.current_buffer(), weechat.buffer_search_main())
----

==== buffer_unmerge

マージされたバッファからバッファのマージを解除する。

プロトタイプ:

[source,C]
----
void weechat_buffer_unmerge (struct t_gui_buffer *buffer,
                             int number);
----

引数:

* 'buffer': バッファへのポインタ
* 'number': 分離したバッファの宛先番号、1
  より小さい場合、バッファは 'buffer' の番号 + 1 になる

C 言語での使用例:

[source,C]
----
weechat_buffer_unmerge (weechat_current_buffer (), 1);
----

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

[source,python]
----
# プロトタイプ
weechat.buffer_unmerge(buffer, number)

# 例
weechat.buffer_unmerge(weechat.current_buffer(), 1)
----

==== buffer_get_integer

バッファプロパティの整数値を返す。

プロトタイプ:

[source,C]
----
int weechat_buffer_get_integer (struct t_gui_buffer *buffer,
                                const char *property);
----

引数:

* 'buffer': バッファへのポインタ
* 'property': プロパティ名:
** 'number': バッファの番号 (1 以上)
** 'layout_number': レイアウトに保存されたバッファの番号
** 'layout_number_merge_order': レイアウトのマージをする際の順番
** 'short_name_is_set': 短い名前が設定されている場合は 1、そうでない場合は 0
** 'type': バッファタイプ (0: フォーマット済み、1: 自由内容)
** 'notify': バッファの通知レベル
** 'num_displayed': バッファを表示しているウィンドウの数
** 'active': バッファがマージされて選択されている場合は 2、バッファが選択されている場合は
   1、バッファがマージされ選択されていない場合は 0
** 'hidden': バッファが隠されている場合は 1、そうでない場合は 0
   _(WeeChat バージョン 1.0 以上で利用可)_
** 'zoomed': バッファがマージとズームされている場合は 1、そうでない場合は 0
   _(WeeChat バージョン 1.0 以上で利用可)_
** 'print_hooks_enabled': プリントフックが有効化されている場合は 1、そうでない場合は 0
** 'day_change': 日付変更メッセージを表示する場合は 1、そうでない場合は 0
   _(WeeChat バージョン 0.4.3 以上で利用可)_
** 'clear': コマンド `/buffer clear` でバッファをクリアできる場合は 1、そうでない場合は 0
   _(WeeChat バージョン 1.0 以上で利用可)_
** 'filter': バッファでフィルタが有効な場合は 1、そうでない場合は 0
   _(WeeChat バージョン 1.0 以上で利用可)_
** 'lines_hidden': バッファに非表示 (フィルタされた) メッセージが 1
   行以上含まれる場合は 1、すべてのメッセージが表示冴えている場合は 0
** 'prefix_max_length': バッファプレフィックスの最大長
** 'time_for_each_line': バッファの各行に時間を表示する場合は
   1 (デフォルト)、そうでない場合は 0
** 'nicklist': ニックネームリストが有効化されている場合は 1、そうでない場合は 0
** 'nicklist_case_sensitive': ニックネームの大文字小文字を区別する場合は 1、そうでない場合は 0
** 'nicklist_max_length': ニックネームの最大長
** 'nicklist_display_groups': グループを表示する場合 1、そうでない場合は 0
** 'nicklist_count': ニックネームリストに含まれるニックネームとグループの数
** 'nicklist_groups_count': ニックネームリストに含まれるグループの数
** 'nicklist_nicks_count': ニックネームリストに含まれるニックネームの数
** 'nicklist_visible_count': 表示されているニックネームとグループの数
** 'input': 入力可能な場合は 1、そうでない場合は 0
** 'input_get_unknown_commands': 未定義のコマンドを入力コールバックに送信する場合は
   1、そうでない場合は 0
** 'input_size': 入力サイズ (バイト単位)
** 'input_length': 入力長 (文字数)
** 'input_pos': バッファ入力におけるカーソル位置
** 'input_1st_display': バッファ入力における 1 文字目
** 'num_history': コマンド履歴の数
** 'text_search': テキスト検索タイプ:
*** 0: 現在検索していない
*** 1: 後方検索 (検索方向: 最古のメッセージに向かって検索)
*** 2: 前方検索 (検索方向: 最新のメッセージに向かって検索)
** 'text_search_exact': テキスト検索で大文字小文字を区別する場合は 1
** 'text_search_found': テキストが見つかった場合は 1、そうでない場合は 0

戻り値:

* プロパティの整数値

C 言語での使用例:

[source,C]
----
weechat_printf (NULL, "my buffer number is: %d",
                weechat_buffer_get_integer (my_buffer, "number"));
----

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

[source,python]
----
# プロトタイプ
value = weechat.buffer_get_integer(buffer, property)

# 例
weechat.prnt("", "my buffer number is: %d" % weechat.buffer_get_integer(my_buffer, "number"))
----

==== buffer_get_string

バッファプロパティの文字列値を返す。

プロトタイプ:

[source,C]
----
const char *weechat_buffer_get_string (struct t_gui_buffer *buffer,
                                       const char *property);
----

引数:

* 'buffer': バッファへのポインタ
* 'property': プロパティ名:
** 'plugin': バッファを作成したプラグインの名前
   ("core" は WeeChat メインバッファ)
** 'name': バッファの名前
** 'full_name': バッファの完全な名前 ("plugin.name") _(WeeChat バージョン 0.3.7 以上で利用可)_
** 'short_name': バッファの短縮名 (注意:
   表示目的以外に使用するのは禁止、ユーザは書き換えることが可能、バッファを検索する際にこれを使ってはいけない、'name'、'full_name'、またはローカル変数
   'channel' を使うこと)
** 'title': バッファのタイトル
** 'input': 入力テキスト
** 'text_search_input': テキスト検索前に保存した入力テキスト
** 'highlight_words': ハイライトする単語のリスト
** 'highlight_regex': ハイライト用の POSIX 拡張正規表現
** 'highlight_tags_restrict': これらのタグを付けられたメッセージだけにハイライトを制限する
** 'highlight_tags': これらのタグを付けられたメッセージを強制的にハイライトする
** 'hotlist_max_level_nicks': 一部のニックネームに対するホットリストレベルの最大値
** 'localvar_xxx': ローカル変数 "xxx" の値
   ("xxx" は読み出す変数の名前)

戻り値:

* プロパティの文字列値

C 言語での使用例:

[source,C]
----
weechat_printf (NULL, "name / short name of buffer are: %s / %s",
                weechat_buffer_get_string (my_buffer, "name"),
                weechat_buffer_get_string (my_buffer, "short_name"));
----

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

[source,python]
----
# プロトタイプ
value = weechat.buffer_get_string(buffer, property)

# 例
weechat.prnt("", "name / short name of buffer are: %s / %s"
    % (weechat.buffer_get_string(my_buffer, "name"),
    weechat.buffer_get_string(my_buffer, "short_name")))
----

==== buffer_get_pointer

バッファプロパティのポインタ値を返す。

プロトタイプ:

[source,C]
----
void *weechat_buffer_pointer (struct t_gui_buffer *buffer,
                              const char *property);
----

引数:

* 'buffer': バッファへのポインタ
* 'property': プロパティ名:
** 'plugin': このバッファを作ったプラグインへのポインタ
   (WeeChat メインバッファの場合は NULL)
** 'highlight_regex_compiled': コンパイル済みの正規表現 'highlight_regex'

戻り値:

* プロパティのポインタ値

C 言語での使用例:

[source,C]
----
weechat_printf (NULL, "plugin pointer of my buffer: %lx",
                weechat_buffer_get_pointer (my_buffer, "plugin"));
----

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

[source,python]
----
# プロトタイプ
value = weechat.buffer_get_pointer(buffer, property)

# 例
weechat.prnt("", "plugin pointer of my buffer: %s" % weechat.buffer_get_pointer(my_buffer, "plugin"))
----

==== buffer_set

バッファプロパティに文字列値を設定。

プロトタイプ:

[source,C]
----
void weechat_buffer_set (struct t_gui_buffer *buffer, const char *property,
                         const char *value);
----

引数:

* 'buffer': バッファへのポインタ
* 'property': プロパティ名 (以下の表を参照)
* 'value': プロパティの新しい値

プロパティ:

[width="100%",cols="^2,4,8",options="header"]
|===
| 名前 | 値 | 説明

| hotlist | "+", "-", WEECHAT_HOTLIST_LOW, WEECHAT_HOTLIST_MESSAGE,
  WEECHAT_HOTLIST_PRIVATE, WEECHAT_HOTLIST_HIGHLIGHT, "-1" |
  "+": ホットリストを有効化 (グローバル設定、バッファへのポインタは使われない) +
  "-": ホットリストを無効化 (グローバル設定、バッファへのポインタは使われない) +
  優先度: この優先度でホットリストにバッファを追加 +
  "-1": ホットリストからバッファを削除 _(WeeChat バージョン 1.0 以上で利用可)_

| completion_freeze | "0" または "1" |
  "0": 補完を止める (デフォルト)
  (グローバル設定、バッファへのポインタは使われない) +
  "1": コマンドラインが更新された際に補完を継続する
  (グローバル設定、バッファへのポインタは使われない)

| unread | - |
  バッファの最後の行の後に未読マーカーを設定

| display | "1" または "auto" |
  "1": 指定したバッファを現在のウィンドウに表示 +
  "auto": 指定したバッファを現在のウィンドウに表示、読了マーカーをリセットしない

| hidden +
  _(WeeChat バージョン 1.0 以上で利用可)_ | "0" または "1" |
  "0": バッファを隠すことを止める +
  "1": バッファを隠す

| number | 番号 |
  指定したバッファをこの番号に移動

| name | 任意の文字列 |
  指定したバッファの新しい名前を設定

| short_name | 任意の文字列 |
  指定したバッファの新しい短縮名を設定

| type | "formatted" または "free" |
  バッファのタイプを設定: "formatted" (チャットメッセージ用)、または
  "free" (自由内容用); 値が "free" の場合、'clear' プロパティは強制的に
  "0" に設定されます _(WeeChat バージョン 1.0 以上で利用可)_

| notify | "0", "1", "2", "3" |
  バッファの通知レベルを設定: "0" = ホットリストに追加しない、"1" =
  ハイライトされた場合のみ追加、"2" = ハイライトされた場合とメッセージを受信した場合に追加、"3" =
  任意のメッセージを受信した場合に追加

| print_hooks_enabled | "0" or "1" |
  プリントフックを無効化する場合は "0"、有効化する場合は "1" (新規バッファに対するデフォルト)

| day_change +
  _(WeeChat バージョン 0.4.3 以上で利用可)_ | "0" または "1" |
  日付変更メッセージを隠す場合は "0"、表示する場合は
  "1" (新規バッファに対するデフォルト)

| clear +
  _(WeeChat バージョン 1.0 以上で利用可)_ | "0" または "1" |
  ユーザからのコマンド `/buffer clear` でバッファのクリアを禁止する場合は "0"、
  バッファのクリアを許可する場合は "1" (新規バッファに対するデフォルト)
   (注意: この値が "0" に設定されていたとしても、関数
   <<_buffer_clear,weechat_buffer_clear>> を使えばバッファをクリアすることが可能です)

| filter +
  _(WeeChat バージョン 1.0 以上で利用可)_ | "0" または "1" |
  "0": バッファでフィルタを無効化 +
  "1": バッファでフィルタを有効化

| title | 任意の文字列 |
  指定したバッファの新しいタイトルを設定

| time_for_each_line | "0" または "1" |
  バッファのすべての行に時間を表示しない場合は "0"、表示する場合は
  "1" (新規バッファに対するデフォルト)

| nicklist | "0" または "1" |
  バッファのニックネームリストを表示しない場合は "0"、表示する場合は "1"

| nicklist_case_sensitive | "0" または "1" |
  ニックネームリストで大文字小文字を区別しない場合は "0"、区別する場合は "1"

| nicklist_display_groups | "0" または "1" |
  ニックネームリストグループを隠す場合は "0"、表示する場合は "1"

| highlight_words | "-" または単語のコンマ区切りリスト |
  任意のハイライトを無効化する場合は特殊値
  "-"、または指定したバッファ内でハイライトする単語のコンマ区切りリスト、例:
  "abc,def,ghi"

| highlight_words_add | 単語のコンマ区切りリスト |
  指定したバッファ内でハイライトする単語のコンマ区切りリスト、
  これらの単語を指定したバッファ内でハイライトする単語に追加します

| highlight_words_del | 単語のコンマ区切りリスト |
  指定したバッファ内でハイライトする単語から削除する単語のコンマ区切りリスト

| highlight_regex | 任意の文字列 |
  ハイライトする POSIX 拡張正規表現

| highlight_tags_restrict | タグのコンマ区切りリスト |
  指定したバッファ内でこれらのタグをつけられたメッセージだけを対象にハイライトする
  (区切り文字 "+" で論理 "and" を表現することにより複数のタグを組み合わせて使うことができます、例:
  "nick_toto+irc_action")

| highlight_tags | タグのコンマ区切りリスト |
  指定したバッファ内でこれらのタグをつけられたメッセージを強制的にハイライトする
  (区切り文字 "+" で論理 "and" を表現することにより複数のタグを組み合わせて使うことができます、例:
  "nick_toto+irc_action")

| hotlist_max_level_nicks | "nick:level" のコンマ区切りリスト |
  指定したバッファに対するホットリストの最大レベルを付けたニックネームのコンマ区切りリスト
  (レベル: -1: ホットリストに追加しない、0: 低い、1: メッセージ、2:
  プライベート、3: ハイライト)、例: "joe:2,mike:-1,robert:-1" (joe
  さんのメッセージはハイライトされない、mike さんと robert さんはホットリストを変更しない)

| hotlist_max_level_nicks_add | "nick:level" のコンマ区切りリスト |
  ホットリストの最大レベルを付けたニックネームのコンマ区切りリスト、
  これらのニックネームを指定したバッファ内のニックネームに追加します

| hotlist_max_level_nicks_del | ニックネームのコンマ区切りリスト |
  ホットリストの最大レベルから削除するニックネームのコンマ区切りリスト

| key_bind_xxx | 任意の文字列 |
  指定したバッファに対して新しいキー 'xxx'
  を割り当てる、値はキーを押して実行するコマンド

| key_unbind_xxx | - |
  指定したバッファに対してキー 'xxx' の割り当てを解除する

| input | 任意の文字列 |
  バッファ入力に新しい値を設定

| input_pos | 位置 |
  バッファ入力のカーソル位置を設定

| input_get_unknown_commands | "0" または "1" |
  指定したバッファに対する未定義のコマンドを無効にする場合は "0"
  (デフォルト)、未定義のコマンドを受け入れる場合は "1"、例えばユーザが "/unknowncmd"
  を入力した場合、バッファはこれを受け入れる (未定義のコマンドに対するエラーを出さない)

| localvar_set_xxx | 任意の文字列 |
  ローカル変数 'xxx' の新しい値を設定
  (存在しない変数の場合は変数を作成する)

| localvar_del_xxx | - |
  ローカル変数 'xxx' を削除
|===

C 言語での使用例:

[source,C]
----
/* disable hotlist (for all buffers) */
weechat_buffer_set (NULL, "hotlist", "-");

/* enable again hotlist */
weechat_buffer_set (NULL, "hotlist", "+");

/* change buffer name */
weechat_buffer_set (my_buffer, "name", "my_new_name");

/* add new local variable "toto" with value "abc" */
weechat_buffer_set (my_buffer, "localvar_set_toto", "abc");

/* remove local variable "toto" */
weechat_buffer_set (my_buffer, "localvar_del_toto", NULL);
----

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

[source,python]
----
# プロトタイプ
weechat.buffer_set(buffer, property, value)

# 例

# disable hotlist (for all buffers)
weechat.buffer_set("", "hotlist", "-")

# enable again hotlist
weechat.buffer_set("", "hotlist", "+")

# change buffer name
weechat.buffer_set(my_buffer, "name", "my_new_name")

# add new local variable "toto" with value "abc"
weechat.buffer_set(my_buffer, "localvar_set_toto", "abc")

# remove local variable "toto"
weechat.buffer_set(my_buffer, "localvar_del_toto", "")
----

==== buffer_set_pointer

バッファプロパティのポインタ値を設定。

プロトタイプ:

[source,C]
----
void weechat_buffer_set_pointer (struct t_gui_buffer *buffer, const char *property,
                                 void *pointer);
----

引数:

* 'buffer': バッファへのポインタ
* 'property': プロパティ名:
** 'close_callback': close コールバック関数を設定
** 'close_callback_data': close コールバックデータを設定
** 'input_callback': 入力コールバック関数を設定
** 'input_callback_data': 入力コールバックデータを設定
** 'nickcmp_callback': ニックネーム比較コールバック関数を設定
  (ニックネームリストからニックネームを検索する際にこのコールバックを使用) _(WeeChat バージョン 0.3.9 以上で利用可)_
** 'nickcmp_callback_data': ニックネーム比較コールバックデータを設定
   _(WeeChat バージョン 0.3.9 以上で利用可)_
* 'pointer': プロパティの新しいポインタ値

コールバックのプロトタイプ:

[source,C]
----
int close_callback (void *data, struct t_gui_buffer *buffer);

int input_callback (void *data, struct t_gui_buffer *buffer, const char *input_data);

int nickcmp_callback (void *data, struct t_gui_buffer *buffer, const char *nick1, const char *nick2);
----

C 言語での使用例:

[source,C]
----
int
my_close_cb (void *data, struct t_gui_buffer *buffer)
{
    /* ... */
    return WEECHAT_RC_OK;
}

weechat_buffer_set_pointer (my_buffer, "close_callback", &my_close_cb);
----

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

==== buffer_string_replace_local_var

文字列に含まれるバッファローカル変数をその値で展開する。

プロトタイプ:

[source,C]
----
char *weechat_buffer_string_replace_local_var (struct t_gui_buffer *buffer,
                                               const char *string);
----

引数:

* 'buffer': バッファへのポインタ
* 'string': テキストおよび "$var" フォーマットのローカル変数を含む文字列

戻り値:

* ローカル変数を展開した文字列

C 言語での使用例:

[source,C]
----
weechat_buffer_set (my_buffer, "localvar_set_toto", "abc");

char *str = weechat_buffer_string_replace_local_var (my_buffer,
                                                     "test with $toto");
/* str contains "test with abc" */
----

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

[source,python]
----
# プロトタイプ
value = weechat.buffer_string_replace_local_var(buffer, string)

# 例
weechat.buffer_set(my_buffer, "localvar_set_toto", "abc")
str = weechat.buffer_string_replace_local_var(my_buffer, "test with $toto")
# str contains "test with abc"
----

==== buffer_match_list

_WeeChat バージョン 0.3.5 以上で利用可。_

バッファがバッファのリストにマッチすることを確認。

プロトタイプ:

[source,C]
----
int weechat_buffer_match_list (struct t_gui_buffer *buffer, const char *string);
----

引数:

* 'buffer': バッファへのポインタ
* 'string': バッファのコンマ区切りリスト:
** "*" 任意のバッファにマッチ
** 名前の最初に "!" がある場合はその名前を含まない場合にマッチ
** 名前にワイルドカード "*" を使うことができます

戻り値:

* バッファがバッファリストにマッチする場合は 1、そうでない場合は 0

C 言語での使用例:

[source,C]
----
struct t_gui_buffer *buffer = weechat_buffer_search ("irc", "freenode.#weechat");
if (buffer)
{
    weechat_printf (NULL, "%d", weechat_buffer_match_list (buffer, "*"));                    /* 1 */
    weechat_printf (NULL, "%d", weechat_buffer_match_list (buffer, "*,!*#weechat*"));        /* 0 */
    weechat_printf (NULL, "%d", weechat_buffer_match_list (buffer, "irc.freenode.*"));       /* 1 */
    weechat_printf (NULL, "%d", weechat_buffer_match_list (buffer, "irc.oftc.*,python.*"));  /* 0 */
}
----

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

[source,python]
----
# プロトタイプ
match = weechat.buffer_match_list(buffer, string)

# 例
buffer = weechat.buffer_search("irc", "freenode.#weechat")
if buffer:
    weechat.prnt("", "%d" % weechat.buffer_match_list(buffer, "*"))                    # 1
    weechat.prnt("", "%d" % weechat.buffer_match_list(buffer, "*,!*#weechat*"))        # 0
    weechat.prnt("", "%d" % weechat.buffer_match_list(buffer, "irc.freenode.*"))       # 1
    weechat.prnt("", "%d" % weechat.buffer_match_list(buffer, "irc.oftc.*,python.*"))  # 0
----

[[windows]]
=== ウィンドウ

ウィンドウを操作する関数。

==== current_window

現在のウィンドウへのポインタを返す。

プロトタイプ:

[source,C]
----
struct t_gui_window *weechat_current_window ();
----

戻り値:

* 現在のウィンドウへのポインタ

C 言語での使用例:

[source,C]
----
struct t_gui_window *current_window = weechat_current_window ();
----

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

[source,python]
----
# プロトタイプ
window = weechat.current_window()

# 例
current_window = weechat.current_window()
----

==== window_search_with_buffer

_WeeChat バージョン 0.3.5 以上で利用可。_

バッファを表示しているウィンドウへのポインタを返す。

プロトタイプ:

[source,C]
----
struct t_gui_window *weechat_window_search_with_buffer (struct t_gui_buffer *buffer);
----

引数:

* 'buffer': バッファへのポインタ

戻り値:

* バッファを表示しているウィンドウへのポインタ (バッファを表示しているウィンドウが無い場合は NULL)

C 言語での使用例:

[source,C]
----
weechat_printf (NULL,
                "window displaying core buffer: %lx",
                weechat_window_search_with_buffer (weechat_buffer_search_main ()));
----

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

[source,python]
----
# プロトタイプ
window = weechat.window_search_with_buffer(buffer)

# 例
weechat.prnt("", "window displaying core buffer: %s"
    % weechat.window_search_with_buffer(weechat.buffer_search_main()))
----

==== window_get_integer

ウィンドウプロパティの整数値を返す。

プロトタイプ:

[source,C]
----
int weechat_window_get_integer (struct t_gui_window *window,
                                const char *property);
----

引数:

* 'window': ウィンドウへのポインタ
* 'property': プロパティ名:
** 'number': ウィンドウ番号 (1 以上)
** 'win_x': 端末内でのウィンドウの X 座標 (1 列目は 0)
** 'win_y': 端末内でのウィンドウの Y 座標 (1 行目は 0)
** 'win_width': ウィンドウの横幅、文字単位
** 'win_height': ウィンドウの縦幅、文字単位
** 'win_width_pct': ウィンドウ横幅の百分率、親ウィンドウに対する割合
   (例えば 50 は半分を意味する)
** 'win_height_pct': ウィンドウ縦幅の百分率、親ウィンドウに対する割合
   (例えば 50 は半分を意味する)
** 'win_chat_x': チャットウィンドウの X 座標 (1 列目は 0)
** 'win_chat_y': チャットウィンドウの Y 座標 (1 行目は 0)
** 'win_chat_width': チャットウィンドウの横幅、文字単位
** 'win_chat_height': チャットウィンドウの縦幅、文字単位
** 'first_line_displayed': バッファの 1
   行目がスクリーンに表示されている場合は 1、そうでなければ 0
** 'scrolling': ウィンドウでスクロールが有効化されている場合 (最後の行が表示されていない場合) は 1
** 'lines_after': バッファの最終行を表示した後にバッファに追加された行の数
   (スクロール中)

戻り値:

* プロパティの整数値

C 言語での使用例:

[source,C]
----
weechat_printf (NULL, "current window is at position (x,y): (%d,%d)",
                weechat_window_get_integer (weechat_current_window (), "win_x"),
                weechat_window_get_integer (weechat_current_window (), "win_y"));
----

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

[source,python]
----
# プロトタイプ
value = weechat.window_get_integer(window, property)

# 例
weechat.prnt("", "current window is at position (x,y): (%d,%d)"
    % (weechat.window_get_integer(weechat.current_window(), "win_x"),
    weechat.window_get_integer(weechat.current_window(), "win_y")))
----

==== window_get_string

ウィンドウプロパティの文字列値を返す。

[NOTE]
現在この関数を使うことはできません、将来のバージョン用に予約されています。

プロトタイプ:

[source,C]
----
int weechat_window_get_string (struct t_gui_window *window,
                               const char *property);
----

引数:

* 'window': ウィンドウへのポインタ
* 'property': プロパティ名

戻り値:

* プロパティの文字列値

==== window_get_pointer

ウィンドウプロパティのポインタ値を返す。

プロトタイプ:

[source,C]
----
void *weechat_window_get_pointer (struct t_gui_window *window,
                                  const char *property);
----

引数:

* 'window': ウィンドウへのポインタ
* 'property': プロパティ名:
** 'current': 現在のウィンドウへのポインタ
** 'buffer': 指定したウィンドウが表示しているバッファへのポインタ

戻り値:

* プロパティのポインタ値

C 言語での使用例:

[source,C]
----
weechat_printf (NULL,
                "buffer displayed in current window: %lx",
                weechat_window_get_pointer (weechat_current_window (), "buffer"));
----

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

[source,python]
----
# プロトタイプ
value = weechat.window_get_pointer(window, property)

# 例
weechat.prnt("", "buffer displayed in current window: %s"
    % weechat.window_get_pointer(weechat.current_window(), "buffer"))
----

==== window_set_title

ターミナルのタイトルを設定。

プロトタイプ:

[source,C]
----
void weechat_window_set_title (const char *title);
----

引数:

* 'title': ターミナルの新しいタイトル (タイトルをリセットする場合は NULL)

C 言語での使用例:

[source,C]
----
weechat_window_set_title ("new title here");
----

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

[source,python]
----
# プロトタイプ
weechat.window_set_title(window, title)

# 例
weechat.window_set_title("new title here")
----

[[nicklist]]
=== ニックネームリスト

バッファのニックネームリストを操作する関数。

==== nicklist_add_group

ニックネームリストにグループを追加。

プロトタイプ:

[source,C]
----
struct t_gui_nick_group *weechat_nicklist_add_group (struct t_gui_buffer *buffer,
                                                     struct t_gui_nick_group *parent_group,
                                                     const char *name,
                                                     const char *color,
                                                     int visible);
----

引数:

* 'buffer': バッファへのポインタ
* 'parent_group': グループの親へのポインタ、グループに親がない場合 NULL
  (ニックネームリスト)
* 'name': グループ名
* 'color': 色オプション名:
** WeeChat オプション名、例えば 'weechat.color.nicklist_group'
** 任意で背景色をつけた色、例えば 'yellow' や 'yellow,red'
** バーの色名:
*** 'bar_fg': バーの前景色
*** 'bar_delim': バーの区切り文字
*** 'bar_bg': バーの背景色
* 'visible':
** '1': グループとサブグループおよびニックネームを表示
** '0': グループとサブグループおよびニックネームを非表示

[NOTE]
グループ名の前に、1
桁以上の数字とパイプ文字を付けると、この数字を使ってニックネームリスト内のグループをソートします。例えば、グループ
"1|test" と "2|abc" はこの順番で表示されます:
最初に "test" その後に "abc"。

戻り値:

* 新しいグループへのポインタ、エラーが起きた場合は NULL

C 言語での使用例:

[source,C]
----
struct t_gui_nick_group *my_group =
    weechat_nicklist_add_group (my_buffer,
                                my_parent_group,
                                "test_group",
                                "weechat.color.nicklist_group",
                                1);
----

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

[source,python]
----
# プロトタイプ
group = weechat.nicklist_add_group(buffer, parent_group, name, color, visible)

# 例
group = weechat.nicklist_add_group(my_buffer, my_parent_group, "test_group",
    "weechat.color.nicklist_group", 1)
----

==== nicklist_search_group

ニックネームリストからグループを検索。

プロトタイプ:

[source,C]
----
struct t_gui_nick_group *weechat_nicklist_search_group (struct t_gui_buffer *buffer,
                                                        struct t_gui_nick_group *from_group,
                                                        const char *name);
----

引数:

* 'buffer': バッファへのポインタ
* 'from_group':
  このグループのみを検索、全てのニックネームリストから検索する場合は NULL
* 'name': 検索するグループ名

戻り値:

* 見つかったグループへのポインタ、見つからなかった場合は NULL

C 言語での使用例:

[source,C]
----
struct t_gui_nick_group *ptr_group = weechat_nicklist_search_group (my_buffer,
                                                                    NULL, "test_group");
----

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

[source,python]
----
# プロトタイプ
group = weechat.nicklist_search_group(buffer, from_group, name)

# 例
group = weechat.nicklist_search_group(my_buffer, "", "test_group")
----

==== nicklist_add_nick

ニックネームをグループに追加。

プロトタイプ:

[source,C]
----
struct t_gui_nick_group *weechat_nicklist_add_nick (struct t_gui_buffer *buffer,
                                                    struct t_gui_nick_group *group,
                                                    const char *name,
                                                    const char *color,
                                                    const char *prefix,
                                                    const char *prefix_color,
                                                    int visible);
----

引数:

* 'buffer': バッファへのポインタ
* 'group': グループへのポインタ
* 'name': ニックネーム
* 'color': 色オプション名:
*** WeeChat オプション名 (weechat.color.xxx のオプション部分)、例えば 'chat_delimiters'
*** 任意で背景色をつけた色、例えば 'yellow' や 'yellow,red'
*** バーの色名:
**** 'bar_fg': バーの前景色
**** 'bar_delim': バーの区切り文字
**** 'bar_bg': バーの背景色
* 'prefix': ニックネームの前に表示するプレフィックス
* 'prefix_color': 色オプション名:
** WeeChat オプション名 (weechat.color.xxx のオプション部分)、例えば 'chat_delimiters'
** 任意で背景色をつけた色、例えば 'yellow' や 'yellow,red'
** バーの色名:
*** 'bar_fg': バーの前景色
*** 'bar_delim': バーの区切り文字
*** 'bar_bg': バーの背景色
* 'visible':
** '1': ニックネームを表示
** '0': ニックネームを非表示

戻り値:

* 新しいニックネームへのポインタ、エラーが起きた場合は NULL

C 言語での使用例:

[source,C]
----
struct t_gui_nick *my_nick =
    weechat_nicklist_add_nick (my_buffer, my_group,
                               "test_nick",
                               (nick_away) ? "weechat.color.nicklist_away" : "bar_fg",
                               "@", "lightgreen",
                               1);
----

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

[source,python]
----
# プロトタイプ
nick = weechat.nicklist_add_nick(buffer, group, name, color, prefix, prefix_color, visible)

# 例
if nick_away:
    color = "weechat.color.nicklist_away"
else:
    color = "bar_fg"
nick = weechat.nicklist_add_nick(my_buffer, my_group, "test_nick", color, "@", "lightgreen", 1)
----

==== nicklist_search_nick

ニックネームリストからニックネームを検索。

プロトタイプ:

[source,C]
----
struct t_gui_nick *weechat_nicklist_search_nick (struct t_gui_buffer *buffer,
                                                 struct t_gui_nick_group *from_group,
                                                 const char *name);
----

引数:

* 'buffer': バッファへのポインタ
* 'from_group':
  このグループのみを検索、全てのニックネームリストから検索する場合は NULL
* 'name': 検索するニックネーム

戻り値:

* 見つかったニックネームへのポインタ、見つからなかった場合は NULL

C 言語での使用例:

[source,C]
----
struct t_gui_nick *ptr_nick = weechat_nicklist_search_nick (my_buffer,
                                                            NULL, "test_nick");
----

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

[source,python]
----
# プロトタイプ
nick = weechat.nicklist_search_nick(buffer, from_group, name)

# 例
nick = weechat.nicklist_search_nick(my_buffer, "", "test_nick")
----

==== nicklist_remove_group

ニックネームリストからグループを削除。

プロトタイプ:

[source,C]
----
void weechat_nicklist_remove_group (struct t_gui_buffer *buffer,
                                    struct t_gui_nick_group *group);
----

引数:

* 'buffer': バッファへのポインタ
* 'group': 削除するグループへのポインタ (同時に全てのサブグループおよびニックネームを削除)

C 言語での使用例:

[source,C]
----
weechat_nicklist_remove_group (my_buffer, my_group);
----

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

[source,python]
----
# プロトタイプ
weechat.nicklist_remove_group(buffer, group)

# 例
weechat.nicklist_remove_group(my_buffer, my_group)
----

==== nicklist_remove_nick

ニックネームリストからニックネームを削除。

プロトタイプ:

[source,C]
----
void weechat_nicklist_remove_nick (struct t_gui_buffer *buffer,
                                   struct t_gui_nick *nick);
----

引数:

* 'buffer': バッファへのポインタ
* 'nick': 削除するニックネームへのポインタ

C 言語での使用例:

[source,C]
----
weechat_nicklist_remove_nick (my_buffer, my_nick);
----

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

[source,python]
----
# プロトタイプ
weechat.nicklist_remove_nick(buffer, nick)

# 例
weechat.nicklist_remove_nick(my_buffer, my_nick)
----

==== nicklist_remove_all

ニックネームリストから全てのグループおよびニックネームを削除。

プロトタイプ:

[source,C]
----
void weechat_nicklist_remove_all (struct t_gui_buffer *buffer);
----

引数:

* 'buffer': バッファへのポインタ

C 言語での使用例:

[source,C]
----
weechat_nicklist_remove_all (my_buffer);
----

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

[source,python]
----
# プロトタイプ
weechat.nicklist_remove_all(buffer)

# 例
weechat.nicklist_remove_all(my_buffer)
----

==== nicklist_get_next_item

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

ニックネームリストから次のグループまたはニックネームを取得 (主にニックネームリストを表示する際に利用)。

プロトタイプ:

[source,C]
----
void weechat_nicklist_get_next_item (struct t_gui_buffer *buffer,
                                     struct t_gui_nick_group **group,
                                     struct t_gui_nick **nick);
----

引数:

* 'buffer': バッファへのポインタ
* 'group': グループへのポインタへのポインタ
* 'nick': ニックネームへのポインタへのポインタ

C 言語での使用例:

[source,C]
----
struct t_gui_nick_group *ptr_group;
struct t_gui_nick *ptr_nick;

ptr_group = NULL;
ptr_nick = NULL;
weechat_nicklist_get_next_item (buffer, &ptr_group, &ptr_nick);
while (ptr_group || ptr_nick)
{
    if (ptr_nick)
    {
        /* nick */
        /* ... */
    }
    else
    {
        /* group */
        /* ... */
    }
    weechat_nicklist_get_next_item (buffer, &ptr_group, &ptr_nick);
}
----

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

==== nicklist_group_get_integer

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

グループプロパティの整数値を返す。

プロトタイプ:

[source,C]
----
int weechat_nicklist_group_get_integer (struct t_gui_buffer *buffer,
                                        struct t_gui_nick_group *group,
                                        const char *property);
----

引数:

* 'buffer': バッファへのポインタ
* 'group': グループへのポインタ
* 'property': プロパティ名:
** 'visible': グループが表示されている場合は 1、そうでない場合は 0
** 'level': グループレベル (ルートは 0)

戻り値:

* プロパティの整数値

C 言語での使用例:

[source,C]
----
int visible = weechat_nicklist_group_get_integer (buffer, group, "visible");
----

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

[source,python]
----
# プロトタイプ
value = weechat.nicklist_group_get_integer(buffer, group, property)

# 例
visible = weechat.nicklist_group_get_integer(buffer, group, "visible")
----

==== nicklist_group_get_string

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

グループプロパティの文字列値を返す。

プロトタイプ:

[source,C]
----
const char *weechat_nicklist_group_get_string (struct t_gui_buffer *buffer,
                                               struct t_gui_nick_group *group,
                                               const char *property);
----

引数:

* 'buffer': バッファへのポインタ
* 'group': グループへのポインタ
* 'property': プロパティ名:
** 'name': グループの名前
** 'color': ニックネームリストのグループ色

戻り値:

* プロパティの文字列値

C 言語での使用例:

[source,C]
----
const char *color = weechat_nicklist_group_get_string (buffer, group, "color");
----

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

[source,python]
----
# プロトタイプ
value = weechat.nicklist_group_get_string(buffer, group, property)

# 例
color = weechat.nicklist_group_get_string(buffer, group, "color")
----

==== nicklist_group_get_pointer

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

グループプロパティのポインタ値を返す。

プロトタイプ:

[source,C]
----
void *weechat_nicklist_group_get_pointer (struct t_gui_buffer *buffer,
                                          struct t_gui_nick_group *group,
                                          const char *property);
----

引数:

* 'buffer': バッファへのポインタ
* 'group': グループへのポインタ
* 'property': プロパティ名:
** 'parent': 親グループへのポインタ

戻り値:

* プロパティのポインタ値

C 言語での使用例:

[source,C]
----
struct t_gui_nick_group *parent = weechat_nicklist_group_get_pointer (buffer, group, "parent");
----

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

[source,python]
----
# プロトタイプ
value = weechat.nicklist_group_get_pointer(buffer, group, property)

# 例
parent = weechat.nicklist_group_get_pointer(buffer, group, "parent")
----

==== nicklist_group_set

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

グループプロパティの文字列値。

プロトタイプ:

[source,C]
----
void weechat_nicklist_group_set (struct t_gui_buffer *buffer,
                                 struct t_gui_nick_group *group,
                                 const char *property,
                                 const char *value);
----

引数:

* 'buffer': バッファへのポインタ
* 'group': グループへのポインタ
* 'property': プロパティ名 (以下の表を参照)
* 'value': プロパティの新しい値

プロパティ:

[width="100%",cols="^2,4,8",options="header"]
|===
| 名前 | 値 | 説明

| color | WeeChat 色オプション名 |
  関数 <<_nicklist_add_group,weechat_nicklist_add_group>>
  の引数 "color" を参照

| visible | "0"、"1" |
  "0" = 非表示状態のグループ、"1" = 表示状態のグループ
|===

C 言語での使用例:

[source,C]
----
/* change group color to "bar_fg" */
weechat_nicklist_group_set (buffer, group, "color", "bar_fg");

/* change group color to yellow */
weechat_nicklist_group_set (buffer, group, "color", "yellow");

/* hide group in nicklist */
weechat_nicklist_group_set (buffer, group, "visible", "0");
----

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

[source,python]
----
# プロトタイプ
weechat.nicklist_group_set(buffer, group, property, value)

# 例

# change group color to "bar_fg"
weechat.nicklist_group_set(buffer, group, "color", "bar_fg")

# change group color to yellow
weechat.nicklist_group_set(buffer, group, "color", "yellow")

# hide group in nicklist
weechat.nicklist_group_set(buffer, group, "visible", "0")
----

==== nicklist_nick_get_integer

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

ニックネームプロパティの整数値を返す。

プロトタイプ:

[source,C]
----
int weechat_nicklist_nick_get_integer (struct t_gui_buffer *buffer,
                                       struct t_gui_nick *nick,
                                       const char *property);
----

引数:

* 'buffer': バッファへのポインタ
* 'nick': ニックネームへのポインタ
* 'property': プロパティ名:
** 'visible': 表示状態のニックネームの場合 1、それ以外の場合は 0

戻り値:

* プロパティの整数値

C 言語での使用例:

[source,C]
----
int visible = weechat_nicklist_nick_get_integer (buffer, nick, "visible");
----

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

[source,python]
----
# プロトタイプ
value = weechat.nicklist_nick_get_integer(buffer, nick, property)

# 例
visible = weechat.nicklist_nick_get_integer(buffer, nick, "visible")
----

==== nicklist_nick_get_string

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

ニックネームプロパティの文字列値を返す。

プロトタイプ:

[source,C]
----
const char *weechat_nicklist_nick_get_string (struct t_gui_buffer *buffer,
                                              struct t_gui_nick *nick,
                                              const char *property);
----

引数:

* 'buffer': バッファへのプロパティ
* 'nick': ニックネームへのポインタ
* 'property': プロパティ名:
** 'name': ニックネームの名前
** 'color': ニックネームリスト内でのニックネームの色
** 'prefix': ニックネームのプレフィックス
** 'prefix_color': ニックネームリスト内でのプレフィックスの色

戻り値:

* プロパティの文字列値

C 言語での使用例:

[source,C]
----
const char *color = weechat_nicklist_nick_get_string (buffer, nick, "color");
----

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

[source,python]
----
# プロトタイプ
value = weechat.nicklist_nick_get_string(buffer, nick, property)

# 例
color = weechat.nicklist_nick_get_string(buffer, nick, "color")
----

==== nicklist_nick_get_pointer

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

ニックネームプロパティのポインタ値を返す。

プロトタイプ:

[source,C]
----
void *weechat_nicklist_nick_get_pointer (struct t_gui_buffer *buffer,
                                         struct t_gui_nick *nick,
                                         const char *property);
----

引数:

* 'buffer': バッファへのポインタ
* 'nick': ニックネームへのポインタ
* 'property': プロパティ名:
** 'group': 指定したニックネームを含むグループへのポインタ

戻り値:

* プロパティのポインタ値

C 言語での使用例:

[source,C]
----
struct t_gui_nick_group *group = weechat_nicklist_nick_get_pointer (buffer, nick, "group");
----

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

[source,python]
----
# プロトタイプ
value = weechat.nicklist_nick_get_pointer(buffer, nick, property)

# 例
group = weechat.nicklist_nick_get_pointer(buffer, nick, "group")
----

==== nicklist_nick_set

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

ニックネームプロパティの文字列値を設定。

プロトタイプ:

[source,C]
----
void weechat_nicklist_nick_set (struct t_gui_buffer *buffer,
                                struct t_gui_nick *nick,
                                const char *property,
                                const char *value);
----

引数:

* 'buffer': バッファへのポインタ
* 'nick': ニックネームへのポインタ
* 'property': プロパティ名 (以下の表を参照)
* 'value': プロパティの新しい値

プロパティ:

[width="100%",cols="^2,4,8",options="header"]
|===
| 名前 | 値 | 説明

| color | WeeChat 色オプション名 |
  関数 <<_nicklist_add_nick,weechat_nicklist_add_nick>>
  の引数 "color" を参照

| prefix | 任意の文字列 |
  指定したニックネームのプレフィックス

| prefix_color | WeeChat color option name |
  関数 <<_nicklist_add_nick,weechat_nicklist_add_nick>>
  の引数 "prefix_color" を参照

| visible | "0", "1" |
  "0" = 非表示状態のニックネーム、"1" = 表示状態のニックネーム
|===

C 言語での使用例:

[source,C]
----
/* change nick color to cyan */
weechat_nicklist_nick_set (buffer, nick, "color", "cyan");

/* change prefix to "+" */
weechat_nicklist_nick_set (buffer, nick, "prefix", "+");

/* change prefix color to yellow */
weechat_nicklist_nick_set (buffer, nick, "prefix_color", "yellow");

/* hide nick in nicklist */
weechat_nicklist_nick_set (buffer, nick, "visible", "0");
----

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

[source,python]
----
# プロトタイプ
weechat.nicklist_nick_set(buffer, nick, property, value)

# 例

# change nick color to cyan
weechat.nicklist_nick_set(buffer, nick, "color", "cyan")

# change prefix to "+"
weechat.nicklist_nick_set(buffer, nick, "prefix", "+")

# change prefix color to yellow
weechat.nicklist_nick_set(buffer, nick, "prefix_color", "yellow")

# hide nick in nicklist
weechat.nicklist_nick_set(buffer, nick, "visible", "0")
----

[[bars]]
=== バー

バーを操作する関数。

==== bar_item_search

バー要素を検索。

プロトタイプ:

[source,C]
----
struct t_gui_bar_item *weechat_bar_item_search (const char *name);
----

引数:

* 'name': バー要素の名前

戻り値:

* 見つかったバー要素へのポインタ、バー要素が見つからない場合 NULL

C 言語での使用例:

[source,C]
----
struct t_gui_bar_item *bar_item = weechat_bar_item_search ("myitem");
----

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

[source,python]
----
# プロトタイプ
bar_item = weechat.bar_item_search(name)

# 例
bar_item = weechat.bar_item_search("myitem")
----

==== bar_item_new

_バージョン 0.4.2 で更新。_

新しいバー要素を作成。

プロトタイプ:

[source,C]
----
struct t_gui_bar_item *weechat_bar_item_new (const char *name,
                                             char *(*build_callback)(void *data,
                                                                     struct t_gui_bar_item *item,
                                                                     struct t_gui_window *window,
                                                                     struct t_gui_buffer *buffer,
                                                                     struct t_hashtable *extra_info),
                                             void *build_callback_data);
----

引数:

* 'name': バー要素の名前
* 'build_callback':
  バー要素を作成する際に呼び出す関数、引数と戻り値:
** 'void *data': ポインタ
** 'struct t_gui_bar_item *item': 要素へのポインタ
** 'struct t_gui_window *window':
   ウィンドウへのポインタ (ルートバーの場合は NULL)
** 'struct t_gui_buffer *buffer': ウィンドウに表示されているバッファ
   (ウィンドウが NULL の場合、現在のバッファ) または以下の構文で指定したバー要素に含まれるバッファ:
   "@buffer:item" _(WeeChat バージョン 0.4.2 以上で利用可)_
** 'struct t_hashtable *extra_info': 常に NULL
   (この引数は将来のバージョン用に予約されています) _(WeeChat バージョン 0.4.2 以上で利用可)_
** 戻り値: バー要素の内容
* 'build_callback_data': WeeChat
  が build コールバックを呼び出す際にコールバックに渡すポインタ

戻り値:

* バー要素へのポインタ、エラーが起きた場合は NULL

C 言語での使用例:

[source,C]
----
char *
my_build_callback (void *data,
                   struct t_gui_bar_item *item,
                   struct t_gui_window *window,
                   struct t_gui_buffer *buffer,
                   struct t_hashtable *extra_info)
{
    return strdup ("my content");
}

struct t_gui_bar_item *my_item = weechat_bar_item_new ("myitem",
                                                       &my_build_callback,
                                                       NULL);
----

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

[IMPORTANT]
0.4.1 より古いバージョンに対する互換性のために、デフォルトのコールバックに渡す引数の個数は
3 個です: 'data' 、'item' 、'window' ('buffer' と 'extra_info' は渡されません)。 +
全ての引数を受け取るコールバックを使う場合は、名前の前に "(extra)"
をつけてください、以下の例を参照 (WeeChat ≥ 0.4.2 でのみ有効)。

[source,python]
----
# プロトタイプ
bar_item = weechat.bar_item_new(name, build_callback, build_callback_data)

# 例 (コールバックに "buffer" と "extra_info" を除いた引数を渡す)
def my_build_callback(data, item, window):
    return "my content"

bar_item = weechat.bar_item_new("myitem", "my_build_callback", "")

# 例 (コールバックに全ての引数を渡す、WeeChat バージョン 0.4.2 以上で利用可)
def my_build_callback2(data, item, window, buffer, extra_info):
    return "my content"

bar_item2 = weechat.bar_item_new("(extra)myitem2", "my_build_callback2", "")  # WeeChat ≥ 0.4.2
----

==== bar_item_update

build コールバックを呼び出してバー要素の内容を更新。

プロトタイプ:

[source,C]
----
void weechat_bar_item_update (const char *name);
----

引数:

* 'name': バー要素の名前

C 言語での使用例:

[source,C]
----
weechat_bar_item_update ("myitem");
----

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

[source,python]
----
# プロトタイプ
weechat.bar_item_update(name)

# 例
weechat.bar_item_update("myitem")
----

==== bar_item_remove

バー要素を削除。

プロトタイプ:

[source,C]
----
void weechat_bar_item_remove (struct t_gui_bar_item *item);
----

引数:

* 'item': バー要素へのポインタ

C 言語での使用例:

[source,C]
----
weechat_bar_item_remove (&my_item);
----

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

[source,python]
----
# プロトタイプ
weechat.bar_item_remove(item)

# 例
weechat.bar_item_remove(myitem)
----

==== bar_search

バーを検索。

プロトタイプ:

[source,C]
----
struct t_gui_bar *weechat_bar_search (const char *name);
----

引数:

* 'name': バーの名前

戻り値:

* 見つかったバーへのポインタ、見つからなかった場合は NULL

C 言語での使用例:

[source,C]
----
struct t_gui_bar *bar = weechat_bar_search ("mybar");
----

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

[source,python]
----
# プロトタイプ
bar = weechat.bar_search(name)

# 例
bar = weechat.bar_search("mybar")
----

==== bar_new

新しいバーを作成。

プロトタイプ:

[source,C]
----
struct t_gui_bar *weechat_bar_new (const char *name,
                                   const char *hidden,
                                   const char *priority,
                                   const char *type,
                                   const char *condition,
                                   const char *position,
                                   const char *filling_top_bottom,
                                   const char *filling_left_right,
                                   const char *size,
                                   const char *size_max,
                                   const char *color_fg,
                                   const char *color_delim,
                                   const char *color_bg,
                                   const char *separator,
                                   const char *items);
----

引数:

* 'name': バーの名前
* 'hidden':
** 'on': バーを非表示
** 'off': バーを表示
* 'priority': バーの優先度 (整数)
* 'type':
** 'root': ウィンドウの外に 1 回だけ表示されたバー
** 'window': 各ウィンドウに表示されたバー
* 'condition': バーの表示位置:
** 'active': アクティブウィンドウのみに表示されているバー
** 'inactive': 非アクティブウィンドウのみに表示されているバー
** 'nicklist': ニックネームリストを持つウィンドウに表示されているバー
** 評価された式: 'WeeChat ユーザガイド' のバーに関する章を参照
* 'position': 'top' 、'bottom' 、'left' 、'right'
* 'filling_top_bottom':
** 'horizontal': 要素は水平方向に詰め込まれている (各要素の後に間隔)
** 'vertical': 要素は垂直方向に詰め込まれている (各要素の後に行)
** 'columns_horizontal': 要素は水平方向に詰め込まれている、列と一緒に表示
** 'columns_vertical': 要素は垂直方向に詰め込まれている、列と一緒に表示
* 'filling_left_right':
** 'horizontal': 要素は水平方向に詰め込まれている (各要素の後に間隔)
** 'vertical': 要素は垂直方向に詰め込まれている (各要素の後に行)
** 'columns_horizontal': 要素は水平方向に詰め込まれている、列と一緒に表示
** 'columns_vertical': 要素は垂直方向に詰め込まれている、列と一緒に表示
* 'size': バーのサイズ、文字単位 (0 は自動サイズ)
* 'size_max': バーの最大サイズ (0 は最大サイズが指定されていない)
* 'color_fg': バーのテキスト色
* 'color_delim': バーの区切り文字の色
* 'color_bg': バーの背景色
* 'separator':
** 'on': バーには他のウィンドウおよびバーとの区切り行がある
** 'off': 区切り無し
* 'items': バーの要素のリスト、コンマ (要素の間に間隔)、または
  "+" (要素の間に間隔を開けない) 区切り

戻り値:

* 新しいバーへのポインタ、エラーが起きた場合は NULL

C 言語での使用例:

[source,C]
----
struct t_gui_bar *my_bar = weechat_bar_new ("mybar",
                                            "off",
                                            "100",
                                            "window",
                                            "",
                                            "top",
                                            "horizontal",
                                            "vertical",
                                            "0",
                                            "5",
                                            "default",
                                            "cyan",
                                            "blue",
                                            "off",
                                            "time,buffer_number+buffer_name");
----

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

[source,python]
----
# プロトタイプ
bar = weechat.bar_new(name, hidden, priority, type, condition, position,
    filling_top_bottom, filling_left_right, size, size_max,
    color_fg, color_delim, color_bg, separator, items)

# 例
bar = weechat.bar_new("mybar", "off", "100", "window", "", "top", "horizontal", "vertical",
    "0", "5", "default", "cyan", "blue", "off", "time,buffer_number+buffer_name")
----

==== bar_set

バープロパティに新しい値を設定。

プロトタイプ:

[source,C]
----
int weechat_bar_set (struct t_gui_bar *bar, const char *property,
                     const char *value);
----

引数:

* 'bar': バーへのポインタ
* 'property': name、hidden、priority、conditions、position、filling_top_bottom、filling_left_right、size、size_max、color_fg、color_delim、color_bg、separator、items
  (<<_bar_new,weechat_bar_new>>
  を参照)
* 'value': プロパティの新しい値

戻り値:

* 新しい値を設定した場合は 1、エラーが起きた場合は 0

C 言語での使用例:

[source,C]
----
weechat_bar_set (mybar, "position", "bottom");
----

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

[source,python]
----
# プロトタイプ
weechat.bar_set(bar, property, value)

# 例
weechat.bar_set(my_bar, "position", "bottom")
----

==== bar_update

スクリーン上のバーの内容を更新。

プロトタイプ:

[source,C]
----
void weechat_bar_update (const char *name);
----

引数:

* 'name': バーの名前

C 言語での使用例:

[source,C]
----
weechat_bar_update ("mybar");
----

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

[source,python]
----
# プロトタイプ
weechat.bar_update(name)

# 例
weechat.bar_update("mybar")
----

==== bar_remove

バーを削除。

プロトタイプ:

[source,C]
----
void weechat_bar_remove (struct t_gui_bar *bar);
----

引数:

* 'bar': バーへのポインタ

C 言語での使用例:

[source,C]
----
weechat_bar_remove (mybar);
----

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

[source,python]
----
# プロトタイプ
weechat.bar_remove(bar)

# 例
weechat.bar_remove(my_bar)
----

[[commands]]
=== コマンド

WeeChat コマンドを実行する関数。

==== command

_バージョン 1.1 で更新。_

コマンドを実行するか、バッファにテキストを送信。

プロトタイプ:

[source,C]
----
int weechat_command (struct t_gui_buffer *buffer, const char *command);
----

引数:

* 'buffer': バッファへのポインタ
  (コマンドは指定したバッファで実行されます、現在のバッファで実行するには NULL を指定してください)
* 'command': 実行するコマンド ("/"
  で始まっている場合)、またはバッファに送信するテキスト

戻り値: (_WeeChat バージョン 1.1 以上で利用可_)

* 'WEECHAT_RC_OK' 成功した場合
* 'WEECHAT_RC_ERROR' エラーが起きた場合

C 言語での使用例:

[source,C]
----
int rc;
rc = weechat_command (weechat_buffer_search ("irc", "freenode.#weechat"),
                      "/whois FlashCode");
----

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

[source,python]
----
# プロトタイプ
weechat.command(buffer, command)

# 例
rc = weechat.command(weechat.buffer_search("irc", "freenode.#weechat"), "/whois FlashCode")
----

[[network]]
=== ネットワーク

ネットワーク関数。

==== network_pass_proxy

プロキシへの接続および認証を確立する。

[IMPORTANT]
この関数は connect() の呼び出しを遮断します、このため connect() を呼び出す場合は
WeeChat がこれを遮断しないように必ずフォークしたプロセスの中で行ってください。

プロトタイプ:

[source,C]
----
int weechat_network_pass_proxy (const char *proxy,
                                int sock,
                                const char *address,
                                int port);
----

引数:

* 'proxy': 使用するプロキシ名
* 'sock': 使用するソケット
* 'address': アドレス (ホスト名または IP アドレス)
* 'port': ポート番号

戻り値:

* 接続が確立された場合は 1、エラーが起きた場合は 0

C 言語での使用例:

[source,C]
----
if (weechat_network_pass_proxy ("my_proxy", sock, "chat.freenode.net", 6667))
{
    /* OK */
}
else
{
    /* error */
}
----

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

==== network_connect_to

_バージョン 0.4.3 で更新。_

リモートホストとの接続を確立する。

[IMPORTANT]
この関数は connect() の呼び出しを遮断します、このため connect() を呼び出す場合は
WeeChat がこれを遮断しないように必ずフォークしたプロセスの中で行ってください。

プロトタイプ:

[source,C]
----
int weechat_network_connect_to (const char *proxy,
                                struct sockaddr *address,
                                socklen_t address_length);
----

引数:

* 'proxy': 使用するプロキシ名
* 'address': 接続先のアドレス (ポート番号を含む)
* 'address_length': 引数 'address' の長さ

戻り値:

* 接続が確立した場合はソケット番号 (>= 0)、エラーが起きた場合は -1

C 言語での使用例:

[source,C]
----
struct sockaddr *addr;
socklen_t length;
int sock;

/* allocate/set address and port in 'addr', set 'length' */
/* ... */

sock = weechat_network_connect_to (NULL, addr, length);
if (sock >= 0)
{
    /* OK */
}
else
{
    /* error */
}
----

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

[[infos]]
=== 情報

情報を取得する関数。

==== info_get

文字列型で WeeChat またはプラグインからの情報を返す。

プロトタイプ:

[source,C]
----
const char *weechat_info_get (const char *info_name, const char *arguments);
----

引数:

* 'info_name': 読み出す情報の名前 (以下の表を参照)
* 'arguments': 指定した情報に対する引数
  (任意、引数を指定しない場合は NULL)

戻り値:

* 指定した情報を含む文字列、エラーが起きた場合は NULL

情報:

include::autogen/plugin_api/infos.asciidoc[]

C 言語での使用例:

[source,C]
----
weechat_printf (NULL, "Current WeeChat version is: %s (compiled on %s)",
                weechat_info_get ("version", NULL),
                weechat_info_get ("date", NULL));
weechat_printf (NULL, "WeeChat home is: %s",
                weechat_info_get ("weechat_dir", NULL));
----

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

[source,python]
----
# プロトタイプ
value = weechat.info_get(info_name, arguments)

# 例
weechat.prnt("", "Current WeeChat version is: %s (compiled on %s)"
    % (weechat.info_get("version", ""), weechat.info_get("date", ""))
weechat.prnt("", "WeeChat home is: %s" % weechat.info_get("weechat_dir", ""))
----

==== info_get_hashtable

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

ハッシュテーブルで WeeChat またはプラグインからの情報を返す。

プロトタイプ:

[source,C]
----
struct t_hashtable *weechat_info_get_hashtable (const char *info_name,
                                                struct t_hashtable *hashtable);
----

引数:

* 'info_name': 読み出す情報の名前 (以下の表を参照)
* 'hashtable': 引数を含むハッシュテーブル (指定した情報に依存)
  (任意、引数を指定しない場合は NULL)

戻り値:

* 指定した情報を含むハッシュテーブル、エラーが起きた場合は NULL

情報:

include::autogen/plugin_api/infos_hashtable.asciidoc[]

C 言語での使用例:

[source,C]
----
struct t_hashtable *hashtable_in, *hashtable_out;

hashtable_in = weechat_hashtable_new (8,
                                      WEECHAT_HASHTABLE_STRING,
                                      WEECHAT_HASHTABLE_STRING,
                                      NULL,
                                      NULL);
if (hashtable_in)
{
    weechat_hashtable_set (
        hashtable_in,
        "message",
        "@time=2015-06-27T16:40:35.000Z :nick!user@host PRIVMSG #weechat :hello!");
    hashtable_out = weechat_info_get_hashtable ("irc_message_parse",
                                                hashtable_in);
    /*
     * now hashtable_out has following keys/values:
     *   "tags"                : "time=2015-06-27T16:40:35.000Z"
     *   "message_without_tags": ":nick!user@host PRIVMSG #weechat :hello!"
     *   "nick"                : "nick"
     *   "host"                : "nick!user@host"
     *   "command"             : "PRIVMSG"
     *   "channel"             : "#weechat"
     *   "arguments"           : "#weechat :hello!"
     *   "text"                : "hello!"
     *   "pos_text"            : "65"
     */
    weechat_hashtable_free (hashtable_in);
    weechat_hashtable_free (hashtable_out);
}
----

[NOTE]
"irc_message_parse" の出力に関するより詳しい情報を得るには
'WeeChat スクリプト作成ガイド' をご覧ください。

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

[source,python]
----
# プロトタイプ
dict = weechat.info_get_hashtable(info_name, dict_in)

# 例
dict_in = {"message": ":nick!user@host PRIVMSG #weechat :message here"}
weechat.prnt("", "message parsed: %s"
             % weechat.info_get_hashtable("irc_message_parse", dict_in))
----

[[infolists]]
=== インフォリスト

インフォリストは "要素" の配列であり、各要素には変数が含まれています。

例えば、インフォリスト "irc_server" には N 個 (N は定義済みの IRC サーバの数)
の要素が含まれています。それぞれの要素には "name"、"buffer"、"is_connected"
などの変数が含まれています。

各要素には型と値があり、以下の型を使うことができます:

* 'integer': 任意の整数値
* 'string': 任意の文字列値
* 'pointer': 任意のポインタ
* 'buffer': 任意のデータを含む固定長のバッファ
* 'time': 時刻値

==== infolist_new

新しいインフォリストを作成。

プロトタイプ:

[source,C]
----
struct t_infolist *weechat_infolist_new ();
----

戻り値:

* 新しいインフォリストへのポインタ

C 言語での使用例:

[source,C]
----
struct t_infolist *infolist = weechat_infolist_new ();
----

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

[source,python]
----
# プロトタイプ
infolist = weechat.infolist_new()

# 例
infolist = weechat.infolist_new()
----

==== infolist_new_item

インフォリストに要素を追加。

プロトタイプ:

[source,C]
----
struct t_infolist_item *weechat_infolist_new_item (struct t_infolist *infolist);
----

引数:

* 'infolist': インフォリストへのポインタ

戻り値:

* 新しい要素へのポインタ

C 言語での使用例:

[source,C]
----
struct t_infolist_item *item = weechat_infolist_new_item (infolist);
----

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

[source,python]
----
# プロトタイプ
item = weechat.infolist_new_item(infolist)

# 例
item = weechat.infolist_new_item(infolist)
----

==== infolist_new_var_integer

インフォリストの要素に整数変数を追加。

プロトタイプ:

[source,C]
----
struct t_infolist_var *weechat_infolist_new_var_integer (struct t_infolist_item *item,
                                                         const char *name,
                                                         int value);
----

引数:

* 'item': インフォリストの要素へのポインタ
* 'name': 変数名
* 'value': 整数値

戻り値:

* 新しい値へのポインタ

C 言語での使用例:

[source,C]
----
struct t_infolist_var *var = weechat_infolist_new_var_integer (item,
                                                               "my_integer",
                                                               123);
----

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

[source,python]
----
# プロトタイプ
var = weechat.infolist_new_var_integer(item, name, value)

# 例
var = weechat.infolist_new_var_integer(item, "my_integer", 123)
----

==== infolist_new_var_string

インフォリストの要素に文字列変数を追加。

プロトタイプ:

[source,C]
----
struct t_infolist_var *weechat_infolist_new_var_string (struct t_infolist_item *item,
                                                        const char *name,
                                                        const char *value);
----

引数:

* 'item': インフォリストの要素へのポインタ
* 'name': 変数名
* 'value': 文字列値

戻り値:

* 新しい値へのポインタ

C 言語での使用例:

[source,C]
----
struct t_infolist_var *var = weechat_infolist_new_var_string (item,
                                                              "my_string",
                                                              "value");
----

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

[source,python]
----
# プロトタイプ
var = weechat.infolist_new_var_string(item, name, value)

# 例
var = weechat.infolist_new_var_string(item, "my_string", "value")
----

==== infolist_new_var_pointer

インフォリストの要素にポインタ変数を追加。

プロトタイプ:

[source,C]
----
struct t_infolist_var *weechat_infolist_new_var_pointer (struct t_infolist_item *item,
                                                         const char *name,
                                                         void *pointer);
----

引数:

* 'item': インフォリストの要素へのポインタ
* 'name': 変数名
* 'pointer': ポインタ

戻り値:

* 新しい値へのポインタ

C 言語での使用例:

[source,C]
----
struct t_infolist_var *var = weechat_infolist_new_var_pointer (item,
                                                               "my_pointer",
                                                               &pointer);
----

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

[source,python]
----
# プロトタイプ
var = weechat.infolist_new_var_pointer(item, name, pointer)

# 例
var = weechat.infolist_new_var_pointer(item, "my_pointer", pointer)
----

==== infolist_new_var_buffer

インフォリストの要素にバッファ変数を追加。

プロトタイプ:

[source,C]
----
struct t_infolist_var *weechat_infolist_new_var_buffer (struct t_infolist_item *item,
                                                        const char *name,
                                                        void *pointer,
                                                        int size);
----

引数:

* 'item': インフォリストの要素へのポインタ
* 'name': 変数名
* 'pointer': バッファへのポインタ
* 'size': バッファのサイズ

戻り値:

* 新しい値へのポインタ

C 言語での使用例:

[source,C]
----
char buffer[256];
/* ... */
struct t_infolist_var *var = weechat_infolist_new_var_buffer (item,
                                                              "my_buffer",
                                                              &buffer,
                                                              sizeof (buffer));
----

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

==== infolist_new_var_time

インフォリストの要素に時刻変数を追加。

プロトタイプ:

[source,C]
----
struct t_infolist_var *weechat_infolist_new_var_time (struct t_infolist_item *item,
                                                      const char *name,
                                                      time_t time);
----

引数:

* 'item': インフォリストの要素へのポインタ
* 'name': 変数名
* 'time': 時刻値

戻り値:

* 新しい値へのポインタ

C 言語での使用例:

[source,C]
----
struct t_infolist_var *var = weechat_infolist_new_var_time (item,
                                                            "my_time",
                                                            time (NULL));
----

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

[source,python]
----
# プロトタイプ
var = weechat.infolist_new_var_time(item, name, time)

# 例
var = weechat.infolist_new_var_time(item, "my_time", int(time.time()))
----

==== infolist_get

WeeChat またはプラグインからインフォリストを返す。

[IMPORTANT]
インフォリストの内容は実データの複製です。そのため多くのデータを含むインフォリスト
("buffer_lines" など) を要求した場合、WeeChat
は全てのデータを複製するのに必要なメモリを確保し、これにはある程度時間がかかります。 +
大きなインフォリストを使う代わりに、hdata を使うほうが望ましいです
(ただしインフォリストは生データである hdata よりも多くの情報を含む場合があります)、<<hdata,hdata>> を参照してください。

プロトタイプ:

[source,C]
----
struct t_infolist *weechat_infolist_get (const char *infolist_name,
                                         void *pointer,
                                         const char *arguments);
----

引数:

* 'infolist_name': 読み出すインフォリストの名前 (以下の表を参照)
* 'pointer': 要素へのポインタ、インフォリストからこの要素のみを取得する場合に指定
  (任意、NULL でも可)
* 'arguments': 指定したインフォリストに対する引数
  (任意、引数が不要の場合は NULL)

戻り値:

* インフォリストへのポインタ、エラーが起きた場合は NULL

インフォリスト:

include::autogen/plugin_api/infolists.asciidoc[]

C 言語での使用例:

[source,C]
----
struct t_infolist *infolist = weechat_infolist_get ("irc_server", NULL, NULL);
----

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

[source,python]
----
# プロトタイプ
infolist = weechat.infolist_get(infolist_name, pointer, arguments)

# 例
infolist = weechat.infolist_get("irc_server", "", "")
----

==== infolist_next

"カーソル" をインフォリスト内の 1 つ後の要素に移動する。あるインフォリストに対するこの関数の呼び出し回数が
1 回目のの場合は、カーソルをインフォリスト内の最初の要素に移動する。

プロトタイプ:

[source,C]
----
int weechat_infolist_next (struct t_infolist *infolist);
----

引数:

* 'infolist': インフォリストへのポインタ

戻り値:

* カーソルが 1 つ後の要素に移動した場合は 1、リストの最後に到達した場合は 0

C 言語での使用例:

[source,C]
----
if (weechat_infolist_next (infolist))
{
    /* read variables in item... */
}
else
{
    /* no more item available */
}
----

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

[source,python]
----
# プロトタイプ
rc = weechat.infolist_next(infolist)

# 例
rc = weechat.infolist_next(infolist)
if rc:
    # read variables in item...
else:
    # no more item available
----

==== infolist_prev

"カーソル" をインフォリスト内の 1 つ前の要素に移動する。あるインフォリストに対するこの関数の呼び出し回数が
1 回目のの場合は、カーソルをインフォリスト内の最後の要素に移動する。

プロトタイプ:

[source,C]
----
int weechat_infolist_prev (struct t_infolist *infolist);
----

引数:

* 'infolist': インフォリストへのポインタ

戻り値:

*  カーソルが 1 つ前の要素に移動した場合は
  1、リストの最初に到達した場合は 0

C 言語での使用例:

[source,C]
----
if (weechat_infolist_prev (infolist))
{
    /* read variables in item... */
}
else
{
    /* no more item available */
}
----

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

[source,python]
----
# プロトタイプ
rc = weechat.infolist_prev(infolist)

# 例
rc = weechat.infolist_prev(infolist)
if rc:
    # read variables in item...
else:
    # no more item available
----

==== infolist_reset_item_cursor

インフォリストの"カーソル"をリセット。

プロトタイプ:

[source,C]
----
void weechat_infolist_reset_item_cursor (struct t_infolist *infolist);
----

引数:

* 'infolist': インフォリストへのポインタ

C 言語での使用例:

[source,C]
----
weechat_infolist_reset_item_cursor (infolist);
----

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

[source,python]
----
# プロトタイプ
weechat.infolist_reset_item_cursor(infolist)

# 例
weechat.infolist_reset_item_cursor(infolist)
----

==== infolist_search_var

_WeeChat バージョン 0.4.3 以上で利用可。_

現在のインフォリスト要素から変数を検索。

プロトタイプ:

[source,C]
----
struct t_infolist_var *weechat_infolist_search_var (struct t_infolist *infolist,
                                                    const char *name);
----

引数:

* 'infolist': インフォリストへのポインタ
* 'name': 変数名

戻り値:

* 見つかった変数へのポインタ、見つからない場合は NULL

C 言語での使用例:

[source,C]
----
if (weechat_infolist_search_var (infolist, "name"))
{
    /* 変数 "name" が存在する場合 */
    /* ... */
}
----

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

[source,python]
----
# プロトタイプ
var = weechat.infolist_search_var(infolist, name)

# 例
if weechat.infolist_search_var(infolist, "name"):
    # 変数 "name" が存在する場合
    # ...
----

==== infolist_fields

現在のインフォリストの要素に対するフィールドのリストを返す。

プロトタイプ:

[source,C]
----
const char *weechat_infolist_fields (struct t_infolist *infolist);
----

引数:

* 'infolist': インフォリストへのポインタ

戻り値:

* 指定したインフォリストの要素に含まれる変数名のリスト。以下の変数名に対応する型の文字を含むコンマ区切りリスト、型は:
  "i" (整数)、"s" (文字列)、"p"
  (ポインタ)、"b" (バッファ)、"t" (時刻)。

C 言語での使用例:

[source,C]
----
const char *fields = weechat_infolist_fields (infolist);
/* fields contains something like:
   "i:my_integer,s:my_string,p:my_pointer,b:my_buffer,t:my_time" */
----

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

[source,python]
----
# プロトタイプ
fields = weechat.infolist_fields(infolist)

# 例
fields = weechat.infolist_fields(infolist)
# fields contains something like:
# "i:my_integer,s:my_string,p:my_pointer,b:my_buffer,t:my_time"
----

==== infolist_integer

現在のインフォリストの要素に含まれる整数変数の値を返す。

プロトタイプ:

[source,C]
----
int weechat_infolist_integer (struct t_infolist *infolist, const char *var);
----

引数:

* 'infolist': インフォリストへのポインタ
* 'var': 変数名 (必ず"整数"型)

戻り値:

* 変数の整数値

C 言語での使用例:

[source,C]
----
weechat_printf (NULL, "integer = %d",
                weechat_infolist_integer (infolist, "my_integer"));
----

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

[source,python]
----
# プロトタイプ
value = weechat.infolist_integer(infolist, var)

# 例
weechat.prnt("", "integer = %d" % weechat.infolist_integer(infolist, "my_integer"))
----

==== infolist_string

現在のインフォリストの要素に含まれる文字列変数の値を返す。

プロトタイプ:

[source,C]
----
const char *weechat_infolist_string (struct t_infolist *infolist, const char *var);
----

引数:

* 'infolist': インフォリストへのポインタ
* 'var': 変数名 (必ず"文字列"型)

戻り値:

* 変数の文字列値

C 言語での使用例:

[source,C]
----
weechat_printf (NULL, "string = %s",
                weechat_infolist_string (infolist, "my_string"));
----

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

[source,python]
----
# プロトタイプ
value = weechat.infolist_string(infolist, var)

# 例
weechat.prnt("", "string = %s" % weechat.infolist_string(infolist, "my_string"))
----

==== infolist_pointer

現在のインフォリストの要素に含まれるポインタ変数の値を返す。

プロトタイプ:

[source,C]
----
void *weechat_infolist_pointer (struct t_infolist *infolist, const char *var);
----

引数:

* 'infolist': インフォリストへのポインタ
* 'var': 変数名 (必ず"ポインタ"型)

戻り値:

* 変数のポインタ値

C 言語での使用例:

[source,C]
----
weechat_printf (NULL, "pointer = 0x%lx",
                weechat_infolist_pointer (infolist, "my_pointer"));
----

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

[source,python]
----
# プロトタイプ
value = weechat.infolist_pointer(infolist, var)

# 例
weechat.prnt("", "pointer = 0x%s" % weechat.infolist_pointer(infolist, "my_pointer"))
----

==== infolist_buffer

現在のインフォリストの要素に含まれるバッファ変数の値を返す。

プロトタイプ:

[source,C]
----
void *weechat_infolist_buffer (struct t_infolist *infolist, const char *var,
                               int *size);
----

引数:

* 'infolist': インフォリストへのポインタ
* 'var': 変数名 (必ず"バッファ"型)
* 'size': 整数変数へのポインタ、バッファサイズを返す

戻り値:

* バッファへのポインタ

C 言語での使用例:

[source,C]
----
int size;
void *pointer = weechat_infolist_buffer (infolist, "my_buffer", &size);
weechat_printf (NULL, "buffer = 0x%lx, size = %d",
                pointer, size);
----

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

==== infolist_time

現在のインフォリストの要素に含まれる時刻変数の値を返す。

プロトタイプ:

[source,C]
----
time_t weechat_infolist_time (struct t_infolist *infolist, const char *var);
----

引数:

* 'infolist': インフォリストへのポインタ
* 'var': 変数名 (必ず"時刻"型)

戻り値:

* 変数の時刻値

C 言語での使用例:

[source,C]
----
weechat_printf (NULL, "time = %ld",
                weechat_infolist_time (infolist, "my_time"));
----

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

[source,python]
----
# プロトタイプ
value = weechat.infolist_time(infolist, var)

# 例
weechat.prnt("", "time = %ld" % weechat.infolist_time(infolist, "my_time"))
----

==== infolist_free

インフォリストの領域を開放。

プロトタイプ:

[source,C]
----
void weechat_infolist_free (struct t_infolist *infolist);
----

引数:

* 'infolist': インフォリストへのポインタ

C 言語での使用例:

[source,C]
----
weechat_infolist_free (infolist);
----

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

[source,python]
----
# プロトタイプ
weechat.infolist_free(infolist)

# 例
weechat.infolist_free(infolist)
----

[[hdata]]
=== Hdata

hdata に対する関数 (WeeChat またはプラグインデータへの直アクセス)。

[IMPORTANT]
hdata を使うことで読み取り専用でデータにアクセスできます。hdata
変数が示すメモリ領域に何かを書き込むことは*厳禁* です。 +
データを更新する場合は必ず関数
<<_hdata_update,weechat_hdata_update>> を使ってください。

==== hdata_new

_WeeChat バージョン 0.3.6 以上で利用可、バージョン 0.3.9 と 0.4.0 で更新。_

新規の hdata を作成。

[NOTE]
.hdata vs インフォリスト
====
Hdata を使うことで高速に WeeChat およびプラグインのデータを読み出す事ができます。hdata
はインフォリストと似ていますが、異なる点もあります:

* hdata はインフォリストに比べて高速でメモリを節約できる: データを複製せずに直接読み出す。
* hdata とインフォリストのデータは異なる場合がある: hdata 構造体には生データ以外は含まれない
  (利便性を考慮してインフォリストには余分なデータが追加されている)
====

プロトタイプ:

[source,C]
----
struct t_hdata *weechat_hdata_new (const char *hdata_name, const char *var_prev, const char *var_next,
                                   int create_allowed, int delete_allowed,
                                   int (*callback_update)(void *data,
                                                          struct t_hdata *hdata,
                                                          void *pointer,
                                                          struct t_hashtable *hashtable),
                                   void *callback_update_data);
----

引数:

* 'hdata_name': hdata の名前
* 'var_prev': 構造体に含まれる変数名。構造体は配列の 1 つ前の要素へのポインタ
  (変数が利用不可能な場合は NULL でも可)
* 'var_next': 構造体に含まれる変数名。構造体は配列の 1 つ後の要素へのポインタ
  (変数が利用不可能な場合は NULL でも可)
* 'create_allowed': 構造体の作成を許可する場合は 1、それ以外の場合は 0
  _(WeeChat バージョン 0.4.0 以上で利用可)_
* 'delete_allowed': 構造体の削除を許可する場合は 1、それ以外の場合は 0
  _(WeeChat バージョン 0.3.9 以上で利用可)_
* 'callback_update': hdata 内のデータを更新する際のコールバック、データの更新を禁止する場合は NULL
  _(WeeChat バージョン 0.3.9 以上で利用可)_ 、引数と戻り値:
** 'void *data': ポインタ
** 'struct t_hdata *hdata': hdata へのポインタ
** 'struct t_hashtable *hashtable': 更新する変数を含むハッシュテーブル
   (<<_hdata_update,weechat_hdata_update>> を参照)
** return value: 更新された変数の数
* 'callback_update_data': WeeChat が update コールバックを呼び出す際にコールバックに渡すポインタ
  _(WeeChat バージョン 0.3.9 以上で利用可)_

戻り値:

* 新しい hdata へのポインタ

C 言語での使用例:

[source,C]
----
struct t_hdata *hdata = weechat_hdata_new ("myplugin_list", "prev", "next", 0, 0, &callback_update, NULL);
----

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

==== hdata_new_var

_WeeChat バージョン 0.3.6 以上で利用可、バージョン 0.3.9 で更新。_

hdata に新しい変数を作成。

プロトタイプ:

[source,C]
----
void weechat_hdata_new_var (struct t_hdata *hdata, const char *name, int offset, int type,
                            int update_allowed, const char *array_size, const char *hdata_name);
----

引数:

* 'hdata': hdata へのポインタ
* 'name': 変数名
* 'offset': 構造体における変数のオフセット
* 'type': 変数型、以下の 1 つ:
** WEECHAT_HDATA_CHAR
** WEECHAT_HDATA_INTEGER
** WEECHAT_HDATA_LONG
** WEECHAT_HDATA_STRING
** WEECHAT_HDATA_SHARED_STRING
** WEECHAT_HDATA_POINTER
** WEECHAT_HDATA_TIME
** WEECHAT_HDATA_HASHTABLE
** WEECHAT_HDATA_OTHER
* 'update_allowed': 変数の更新を許可する場合は 1、禁止する場合は 0
  _(WeeChat バージョン 0.3.9 以上で利用可)_
* 'array_size': 配列でない場合は必ず NULL、配列の場合の値は:
  _(WeeChat バージョン 0.3.9 以上で利用可)_
** hdata に含まれる変数の名前: 配列のサイズはこの名前の変数に収められている
   (配列サイズは動的に変化)
** 整数 (文字列): 配列のサイズは固定
** '*': 自動サイズ: 配列のサイズは値の中に見つかる最初の NULL を元に計算されます
   (文字列、ポインタ、ハッシュテーブル型以外では使えません)
* 'hdata_name': hdata の名前 (変数が hdata を含む構造体へのポインタの場合)

C 言語での使用例:

[source,C]
----
struct t_myplugin_list
{
    char *name;
    struct t_gui_buffer *buffer;
    int tags_count;
    char **tags_array;
    char **string_split;
    struct t_myplugin_list *prev;
    struct t_myplugin_list *next;
};

/* ... */

struct t_hdata *hdata = weechat_hdata_new ("myplugin_list", "prev", "next");
weechat_hdata_new_var (hdata, "name", offsetof (struct t_myplugin_list, name), WEECHAT_HDATA_STRING, 0, NULL, NULL);
weechat_hdata_new_var (hdata, "buffer", offsetof (struct t_myplugin_list, buffer), WEECHAT_HDATA_POINTER, 0, NULL, NULL);
weechat_hdata_new_var (hdata, "tags_count", offsetof (struct t_myplugin_list, tags_count), WEECHAT_HDATA_INTEGER, 0, NULL, NULL);
weechat_hdata_new_var (hdata, "tags_array", offsetof (struct t_myplugin_list, tags_array), WEECHAT_HDATA_STRING, 0, "tags_count", NULL);
weechat_hdata_new_var (hdata, "string_split", offsetof (struct t_myplugin_list, string_split), WEECHAT_HDATA_STRING, 0, "*", NULL);
weechat_hdata_new_var (hdata, "prev", offsetof (struct t_myplugin_list, prev), WEECHAT_HDATA_POINTER, 0, NULL, "myplugin_list");
weechat_hdata_new_var (hdata, "next", offsetof (struct t_myplugin_list, next), WEECHAT_HDATA_POINTER, 0, NULL, "myplugin_list");
----

コードを短くするためにはマクロ "WEECHAT_HDATA_VAR" を使います。

[source,C]
----
WEECHAT_HDATA_VAR(struct t_myplugin_list, name, STRING, 0, NULL, NULL);
WEECHAT_HDATA_VAR(struct t_myplugin_list, buffer, POINTER, 0, NULL, NULL);
WEECHAT_HDATA_VAR(struct t_myplugin_list, tags_count, INTEGER, 0, NULL, NULL);
WEECHAT_HDATA_VAR(struct t_myplugin_list, tags_array, STRING, 0, "tags_count", NULL);
WEECHAT_HDATA_VAR(struct t_myplugin_list, string_split, STRING, 0, "*", NULL);
WEECHAT_HDATA_VAR(struct t_myplugin_list, prev, POINTER, 0, NULL, "myplugin_list");
WEECHAT_HDATA_VAR(struct t_myplugin_list, next, POINTER, 0, NULL, "myplugin_list");
----

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

==== hdata_new_list

_WeeChat バージョン 0.3.6 以上で利用可、バージョン 1.0 で更新。_

hdata に新しいリストへのポインタを作成。

プロトタイプ:

[source,C]
----
void weechat_hdata_new_list (struct t_hdata *hdata, const char *name, void *pointer, int flags);
----

引数:

* 'hdata': hdata へのポインタ
* 'name': 変数名
* 'pointer': リストへのポインタ
* 'flags': 以下の値の組み合わせ: _(WeeChat バージョン 1.0 以上)_
** 'WEECHAT_HDATA_LIST_CHECK_POINTERS': ポインタをチェックする際に使うリスト

C 言語での使用例:

[source,C]
----
struct t_myplugin_list
{
    char *name;
    struct t_gui_buffer *buffer;
    int tags_count;
    char **tags_array;
    char **string_split;
    struct t_myplugin_list *prev;
    struct t_myplugin_list *next;
};

/* ... */

struct t_hdata *hdata = weechat_hdata_new ("myplugin_list", "prev", "next");
weechat_hdata_new_var (hdata, "name", offsetof (struct t_myplugin_list, name), WEECHAT_HDATA_STRING, NULL, NULL);
weechat_hdata_new_var (hdata, "buffer", offsetof (struct t_myplugin_list, buffer), WEECHAT_HDATA_POINTER, NULL, NULL);
weechat_hdata_new_var (hdata, "tags_count", offsetof (struct t_myplugin_list, tags_count), WEECHAT_HDATA_INTEGER, NULL, NULL);
weechat_hdata_new_var (hdata, "tags_array", offsetof (struct t_myplugin_list, tags_array), WEECHAT_HDATA_STRING, "tags_count", NULL);
weechat_hdata_new_var (hdata, "string_split", offsetof (struct t_myplugin_list, string_split), WEECHAT_HDATA_STRING, "*", NULL);
weechat_hdata_new_var (hdata, "prev", offsetof (struct t_myplugin_list, prev), WEECHAT_HDATA_POINTER, NULL, "myplugin_list");
weechat_hdata_new_var (hdata, "next", offsetof (struct t_myplugin_list, next), WEECHAT_HDATA_POINTER, NULL, "myplugin_list");

weechat_hdata_new_list (hdata, "buffers", &buffers, WEECHAT_HDATA_LIST_CHECK_POINTERS);
weechat_hdata_new_list (hdata, "last_buffer", &last_buffer, 0);
----

コードを短くするためにはマクロ "WEECHAT_HDATA_LIST" を使います。

[source,C]
----
WEECHAT_HDATA_LIST(buffers, WEECHAT_HDATA_LIST_CHECK_POINTERS);
WEECHAT_HDATA_LIST(last_buffer, 0);
----

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

==== hdata_get

_WeeChat バージョン 0.3.6 以上で利用可。_

WeeChat 及びプラグイン構造体に対する hdata を返す。

[NOTE]
hdata はデータを含みません、hdata
は構造体における変数の位置を含むただのハッシュテーブル。つまりデータを読み出すためには
hdata と WeeChat 及びプラグインへのポインタが必要です。

プロトタイプ:

[source,C]
----
struct t_hdata *weechat_hdata_get (const char *hdata_name);
----

引数:

* 'hdata_name': hdata の名前

戻り値:

* hdata へのポインタ、エラーが起きた場合は NULL

hdata のリスト:

include::autogen/plugin_api/hdata.asciidoc[]

C 言語での使用例:

[source,C]
----
struct t_hdata *hdata = weechat_hdata_get ("irc_server");
----

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

[source,python]
----
# プロトタイプ
hdata = weechat.hdata_get(hdata_name)

# 例
hdata = weechat.hdata_get("irc_server")
----

==== hdata_get_var_offset

_WeeChat バージョン 0.3.6 以上で利用可。_

hdata における変数のオフセットを返す。

プロトタイプ:

[source,C]
----
int weechat_hdata_get_var_offset (struct t_hdata *hdata, const char *name);
----

引数:

* 'hdata': hdata へのポインタ
* 'name': 変数名

戻り値:

* オフセットの値、エラーが起きた場合は 0

C 言語での使用例:

[source,C]
----
int offset = weechat_hdata_get_var_offset (hdata, "name");
----

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

[source,python]
----
# プロトタイプ
offset = weechat.hdata_get_var_offset(hdata, name)

# 例
offset = weechat.hdata_get_var_offset(hdata, "name")
----

==== hdata_get_var_type

_WeeChat バージョン 0.3.6 以上で利用可。_

hdata 内の変数の型を (整数で) 返す。

プロトタイプ:

[source,C]
----
int weechat_hdata_get_var_type (struct t_hdata *hdata, const char *name);
----

引数:

* 'hdata': hdata へのポインタ
* 'name': 変数名

戻り値:

* 変数の型、エラーが起きた場合は -1

C 言語での使用例:

[source,C]
----
int type = weechat_hdata_get_var_type (hdata, "name");
switch (type)
{
    case WEECHAT_HDATA_CHAR:
        /* ... */
        break;
    case WEECHAT_HDATA_INTEGER:
        /* ... */
        break;
    case WEECHAT_HDATA_LONG:
        /* ... */
        break;
    case WEECHAT_HDATA_STRING:
        /* ... */
        break;
    case WEECHAT_HDATA_SHARED_STRING:
        /* ... */
        break;
    case WEECHAT_HDATA_POINTER:
        /* ... */
        break;
    case WEECHAT_HDATA_TIME:
        /* ... */
        break;
    case WEECHAT_HDATA_HASHTABLE:
        /* ... */
        break;
    case WEECHAT_HDATA_OTHER:
        /* ... */
        break;
    default:
        /* variable not found */
        break;
}
----

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

==== hdata_get_var_type_string

_WeeChat バージョン 0.3.6 以上で利用可。_

変数の型を (文字列で) 返す。

プロトタイプ:

[source,C]
----
const char *weechat_hdata_get_var_type_string (struct t_hdata *hdata, const char *name);
----

引数:

* 'hdata': hdata へのポインタ
* 'name': 変数名

戻り値:

* 変数の型、エラーが起きた場合は NULL

C 言語での使用例:

[source,C]
----
weechat_printf (NULL, "type = %s", weechat_hdata_get_var_type_string (hdata, "name"));
----

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

[source,python]
----
# プロトタイプ
type = weechat.hdata_get_var_type_string(hdata, name)

# 例
weechat.prnt("", "type = %s" % weechat.hdata_get_var_type_string("name"))
----

==== hdata_get_var_array_size

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

hdata に含まれる配列変数のサイズを返す。

プロトタイプ:

[source,C]
----
int weechat_hdata_get_var_array_size (struct t_hdata *hdata, void *pointer, const char *name);
----

引数:

* 'hdata': hdata へのポインタ
* 'pointer': WeeChat および plugin オブジェクトへのポインタ
* 'name': 変数名

戻り値:

* 配列変数のサイズ、配列変数でない場合とエラーが起きた場合は -1

C 言語での使用例:

[source,C]
----
int array_size = weechat_hdata_get_var_array_size (hdata, pointer, "name");
----

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

[source,python]
----
# プロトタイプ
array_size = weechat.hdata_get_var_array_size(hdata, pointer, name)

# 例
array_size = weechat.hdata_get_var_array_size(hdata, pointer, "name")
----

==== hdata_get_var_array_size_string

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

hdata に含まれる配列変数のサイズを (文字列で) 返す。

プロトタイプ:

[source,C]
----
const char *weechat_hdata_get_var_array_size_string (struct t_hdata *hdata, void *pointer,
                                                     const char *name);
----

引数:

* 'hdata': hdata へのポインタ
* 'pointer': WeeChat および plugin オブジェクトへのポインタ
* 'name': 変数名

戻り値:

* 配列変数のサイズの文字列、配列変数でない場合とエラーが起きた場合は
  NULL

C 言語での使用例:

[source,C]
----
const char *array_size = weechat_hdata_get_var_array_size_string (hdata, pointer, "name");
----

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

[source,python]
----
# プロトタイプ
array_size = weechat.hdata_get_var_array_size_string(hdata, pointer, name)

# 例
array_size = weechat.hdata_get_var_array_size_string(hdata, pointer, "name")
----

==== hdata_get_var_hdata

_WeeChat バージョン 0.3.6 以上で利用可。_

hdata に含まれる変数に対応する hdata を返す。

プロトタイプ:

[source,C]
----
const char *weechat_hdata_get_var_hdata (struct t_hdata *hdata, const char *name);
----

引数:

* 'hdata': hdata へのポインタ
* 'name': 変数名

戻り値:

* 変数に対応する、hdata がない場合とエラーが起きた場合は NULL

C 言語での使用例:

[source,C]
----
weechat_printf (NULL, "hdata = %s", weechat_hdata_get_var_hdata (hdata, "name"));
----

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

[source,python]
----
# プロトタイプ
hdata_name = weechat.hdata_get_var_hdata(hdata, name)

# 例
weechat.prnt("", "hdata = %s" % weechat.hdata_get_var_hdata(hdata, "name"))
----

==== hdata_get_var

_WeeChat バージョン 0.3.6 以上で利用可。_

hdata に含まれる変数の内容へのポインタを返す。

プロトタイプ:

[source,C]
----
void *weechat_hdata_get_var (struct t_hdata *hdata, void *pointer, const char *name);
----

引数:

* 'hdata': hdata へのポインタ
* 'pointer': WeeChat および plugin オブジェクトへのポインタ
* 'name': 変数名

戻り値:

* 変数の内容へのポインタ、エラーが起きた場合は NULL

C 言語での使用例:

[source,C]
----
struct t_hdata *hdata = weechat_hdata_get ("buffer");
struct t_gui_buffer *buffer = weechat_buffer_search_main ();
void *pointer = weechat_hdata_get_var (hdata, buffer, "name");
----

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

==== hdata_get_var_at_offset

_WeeChat バージョン 0.3.6 以上で利用可。_

オフセットを使って hdata に含まれる変数を指定し、この内容へのポインタを返す。

プロトタイプ:

[source,C]
----
void *weechat_hdata_get_var_at_offset (struct t_hdata *hdata, void *pointer, int offset);
----

引数:

* 'hdata': hdata へのポインタ
* 'pointer': WeeChat および plugin オブジェクトへのポインタ
* 'name': 変数名

戻り値:

* 変数の内容へのポインタ、エラーが起きた場合は NULL

C 言語での使用例:

[source,C]
----
struct t_hdata *hdata = weechat_hdata_get ("buffer");
struct t_gui_buffer *buffer = weechat_buffer_search_main ();
int offset = weechat_hdata_get_var_offset (hdata, "name");
void *pointer = weechat_hdata_get_var_at_offset (hdata, buffer, offset);
----

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

==== hdata_get_list

_WeeChat バージョン 0.3.6 以上で利用可。_

hdata からリストへのポインタを返す。

プロトタイプ:

[source,C]
----
void *weechat_hdata_get_list (struct t_hdata *hdata, const char *name);
----

引数:

* 'hdata': hdata へのポインタ
* 'name': リスト名

戻り値:

* リストへのポインタ、エラーが起きた場合は NULL

C 言語での使用例:

[source,C]
----
struct t_hdata *hdata = weechat_hdata_get ("buffer");
struct t_gui_buffer *buffers = weechat_hdata_get_list (hdata, "gui_buffers");
----

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

[source,python]
----
# プロトタイプ
list = weechat.hdata_get_list(hdata, name)

# 例
hdata = weechat.hdata_get("buffer")
buffers = weechat.hdata_get_list(hdata, "gui_buffers")
----

==== hdata_check_pointer

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

hdata とリストへのポインタを使ってポインタの妥当性を確認する。

プロトタイプ:

[source,C]
----
int weechat_hdata_check_pointer (struct t_hdata *hdata, void *list, void *pointer);
----

引数:

* 'hdata': hdata へのポインタ
* 'list': リストポインタ; NULL の場合 _(WeeChat バージョン 1.0 以上)_、ポインタは
   hdata に含まれる "check pointers" フラグを持つリストでチェックされます
  (<<_hdata_new_list,weechat_hdata_new_list>>
  を参照)、このフラグを持つリストがない場合、ポインタは妥当とされます。
* 'pointer': 確認するポインタ

戻り値:

* リスト内にポインタが有る場合は 1、無い場合は 0

C 言語での使用例:

[source,C]
----
/* check if a buffer pointer is valid */
struct t_hdata *hdata = weechat_hdata_get ("buffer");
if (weechat_hdata_check_pointer (hdata,
                                 weechat_hdata_get_list (hdata, "gui_buffers"),
                                 ptr_buffer))
{
    /* valid pointer */
}
else
{
    /* invalid pointer */
}
----

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

[source,python]
----
# プロトタイプ
rc = weechat.hdata_check_pointer(hdata, list, pointer)

# 例
hdata = weechat.hdata_get("buffer")
if weechat.hdata_check_pointer(hdata, weechat.hdata_get_list(hdata, "gui_buffers"), ptr_buffer):
    # valid pointer
    # ...
else:
    # invalid pointer
    # ...
----

==== hdata_move

_WeeChat バージョン 0.3.6 以上で利用可。_

リスト内の他の要素にポインタを移動する。

プロトタイプ:

[source,C]
----
void *weechat_hdata_move (struct t_hdata *hdata, void *pointer, int count);
----

引数:

* 'hdata': hdata へのポインタ
* 'pointer': WeeChat および plugin オブジェクトへのポインタ
* 'count': 移動を実行する回数
  (負および正の整数、ゼロは禁止)

戻り値:

* 移動先の要素へのポインタ、エラーが起きた場合は NULL

C 言語での使用例:

[source,C]
----
struct t_hdata *hdata = weechat_hdata_get ("buffer");
struct t_gui_buffer *buffer = weechat_buffer_search_main ();

/* move to next buffer, 2 times */
buffer = weechat_hdata_move (hdata, buffer, 2);

/* move to previous buffer */
if (buffer)
    buffer = weechat_hdata_move (hdata, buffer, -1);
----

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

[source,python]
----
# プロトタイプ
pointer = weechat.hdata_move(hdata, pointer, count)

# 例
hdata = weechat.hdata_get("buffer")
buffer = weechat.buffer_search_main()

# move to next buffer, 2 times
buffer = weechat.hdata_move(hdata, buffer, 2)

# move to previous buffer
if buffer:
    buffer = weechat.hdata_move(hdata, buffer, -1)
----

==== hdata_search

_WeeChat バージョン 0.4.1 以上で利用可。_

リストから要素を検索: リスト内の各要素に対して 'search'
の内容を評価し、マッチする要素が見つかるかリストの最後に到達するまでこれを続ける。

プロトタイプ:

[source,C]
----
void *weechat_hdata_search (struct t_hdata *hdata, void *pointer, const char *search, int move);
----

引数:

* 'hdata': hdata へのポインタ
* 'pointer': WeeChat および plugin オブジェクトへのポインタ
* 'search': 評価する式、式中のデフォルトポインタは hdata の名前
  (デフォルトポインタはリストに含まれる各要素で置換される); 式に関する情報は
  'WeeChat ユーザガイド' のコマンド `/eval` を参照
* 'move': 検索に失敗した後に移動を実行する回数
  (負および正の整数、ゼロは禁止)

戻り値:

* 見つかった要素へのポインタ、見つからなかった場合は NULL

C 言語での使用例:

[source,C]
----
struct t_hdata *hdata = weechat_hdata_get ("irc_server");
void *servers = weechat_hdata_get (hdata, "irc_servers");

/* search irc server with name "freenode" */
void *server = weechat_hdata_search (hdata, servers, "${irc_server.name} == freenode", 1);
if (server)
{
    /* ... */
}
----

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

[source,python]
----
# プロトタイプ
pointer = weechat.hdata_search(hdata, pointer, search, count)

# 例
hdata = weechat.hdata_get("irc_server")
servers = weechat.hdata_get_list(hdata, "irc_servers")

# search irc server with name "freenode"
server = weechat.hdata_search(hdata, servers, "${irc_server.name} == freenode", 1)
if server:
    # ...
----

==== hdata_char

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

hdata を使って構造体に含まれる文字型変数の値を返す。

プロトタイプ:

[source,C]
----
char weechat_hdata_char (struct t_hdata *hdata, void *pointer, const char *name);
----

引数:

* 'hdata': hdata へのポインタ
* 'pointer': WeeChat および plugin オブジェクトへのポインタ
* 'name': 変数名 (必ず"文字型"であること); 配列の場合、"N|name"
  のように名前を指定することが可能。ここで N は配列のインデックス (1 番目は 0)、例: "2|name"

戻り値:

* 文字型変数の値

C 言語での使用例:

[source,C]
----
weechat_printf (NULL, "letter = %c", weechat_hdata_char (hdata, pointer, "letter"));
----

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

[source,python]
----
# プロトタイプ
value = weechat.hdata_char(hdata, pointer, name)

# 例
weechat.prnt("", "letter = %c" % weechat.hdata_char(hdata, pointer, "letter"))
----

==== hdata_integer

_WeeChat バージョン 0.3.6 以上で利用可。_

hdata を使って構造体に含まれる整数型変数の値を返す。

プロトタイプ:

[source,C]
----
int weechat_hdata_integer (struct t_hdata *hdata, void *pointer, const char *name);
----

引数:

* 'hdata': hdata へのポインタ
* 'pointer': WeeChat および plugin オブジェクトへのポインタ
* 'name': 変数名 (必ず"整数型"であること); 配列の場合、"N|name"
  のように名前を指定することが可能。ここで N は配列のインデックス (1 番目は 0)、例: "2|name"

戻り値:

* 整数型変数の値

C 言語での使用例:

[source,C]
----
struct t_hdata *hdata = weechat_hdata_get ("buffer");
struct t_gui_buffer *buffer = weechat_buffer_search_main ();
weechat_printf (NULL, "number = %d", weechat_hdata_integer (hdata, buffer, "number"));
----

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

[source,python]
----
# プロトタイプ
value = weechat.hdata_integer(hdata, pointer, name)

# 例
hdata = weechat.hdata_get("buffer")
buffer = weechat.buffer_search_main()
weechat.prnt("", "number = %d" % weechat.hdata_integer(hdata, buffer, "number"))
----

==== hdata_long

_WeeChat バージョン 0.3.6 以上で利用可。_

hdata を使って構造体に含まれる long 型変数の値を返す。

プロトタイプ:

[source,C]
----
long weechat_hdata_long (struct t_hdata *hdata, void *pointer, const char *name);
----

引数:

* 'hdata': hdata へのポインタ
* 'pointer': WeeChat および plugin オブジェクトへのポインタ
* 'name': 変数名 (必ず "long 型"であること); 配列の場合、"N|name"
  のように名前を指定することが可能。ここで N は配列のインデックス (1 番目は 0)、例: "2|name"

戻り値:

* long 変数の値

C 言語での使用例:

[source,C]
----
weechat_printf (NULL, "longvar = %ld", weechat_hdata_long (hdata, pointer, "longvar"));
----

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

[source,python]
----
# プロトタイプ
value = weechat.hdata_long(hdata, pointer, name)

# 例
weechat.prnt("", "longvar = %ld" % weechat.hdata_long(hdata, pointer, "longvar"))
----

==== hdata_string

_WeeChat バージョン 0.3.6 以上で利用可。_

hdata を使って構造体に含まれる文字列型変数の値を返す。

プロトタイプ:

[source,C]
----
const char *weechat_hdata_string (struct t_hdata *hdata, void *pointer, const char *name);
----

引数:

* 'hdata': hdata へのポインタ
* 'pointer': WeeChat および plugin オブジェクトへのポインタ
* 'name': 変数名 (必ず"文字列型"であること); 配列の場合、"N|name"
  のように名前を指定することが可能。ここで N は配列のインデックス (1 番目は 0)、例: "2|name"

戻り値:

* 文字列変数の値

C 言語での使用例:

[source,C]
----
struct t_hdata *hdata = weechat_hdata_get ("buffer");
struct t_gui_buffer *buffer = weechat_buffer_search_main ();
weechat_printf (NULL, "name = %s", weechat_hdata_string (hdata, buffer, "name"));
----

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

[source,python]
----
# プロトタイプ
value = weechat.hdata_string(hdata, pointer, name)

# 例
hdata = weechat.hdata_get("buffer")
buffer = weechat.buffer_search_main()
weechat.prnt("", "name = %s" % weechat.hdata_string(hdata, buffer, "name"))
----

==== hdata_pointer

_WeeChat バージョン 0.3.6 以上で利用可。_

hdata を使って構造体に含まれるポインタ型変数の値を返す。

プロトタイプ:

[source,C]
----
void *weechat_hdata_pointer (struct t_hdata *hdata, void *pointer, const char *name);
----

引数:

* 'hdata': hdata へのポインタ
* 'pointer': WeeChat および plugin オブジェクトへのポインタ
* 'name': 変数名 (必ず"ポインタ型"であること); 配列の場合、"N|name"
  のように名前を指定することが可能。ここで N は配列のインデックス (1 番目は 0)、例: "2|name"

戻り値:

* ポインタ型変数の値

C 言語での使用例:

[source,C]
----
struct t_hdata *hdata = weechat_hdata_get ("buffer");
struct t_gui_buffer *buffer = weechat_buffer_search_main ();
weechat_printf (NULL, "lines = %lx", weechat_hdata_pointer (hdata, buffer, "lines"));
----

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

[source,python]
----
# プロトタイプ
value = weechat.hdata_pointer(hdata, pointer, name)

# 例
hdata = weechat.hdata_get("buffer")
buffer = weechat.buffer_search_main()
weechat.prnt("", "lines = %lx" % weechat.hdata_pointer(hdata, buffer, "lines"))
----

==== hdata_time

_WeeChat バージョン 0.3.6 以上で利用可。_

hdata を使って構造体に含まれる時刻型変数の値を返す。

プロトタイプ:

[source,C]
----
time_t weechat_hdata_time (struct t_hdata *hdata, void *pointer, const char *name);
----

引数:

* 'hdata': hdata へのポインタ
* 'pointer': WeeChat および plugin オブジェクトへのポインタ
* 'name': 変数名 (必ず"時刻型"であること); 配列の場合、"N|name"
  のように名前を指定することが可能。ここで N は配列のインデックス (1 番目は 0)、例: "2|name"

戻り値:

* 時刻型変数の値

C 言語での使用例:

[source,C]
----
struct t_hdata *hdata = weechat_hdata_get ("buffer");
struct t_gui_buffer *ptr = weechat_buffer_search_main ();
ptr = weechat_hdata_pointer (hdata, ptr, "lines");
if (ptr)
{
    hdata = weechat_hdata_get ("lines");
    ptr = weechat_hdata_pointer (hdata, ptr, "first_line");
    if (ptr)
    {
        hdata = weechat_hdata_get ("line");
        ptr = weechat_hdata_pointer (hdata, ptr, "data");
        if (ptr)
        {
            hdata = weechat_hdata_get ("line_data");
            time_t date = weechat_hdata_time (hdata, hdata, "date");
            weechat_printf (NULL, "time of last line displayed = %s", ctime (&date));
        }
    }
}
----

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

[source,python]
----
# プロトタイプ
value = weechat.hdata_time(hdata, pointer, name)

# 例
buf = weechat.buffer_search_main()
ptr = weechat.hdata_pointer(weechat.hdata_get("buffer"), buf, "lines")
if ptr:
    ptr = weechat.hdata_pointer(weechat.hdata_get("lines"), ptr, "first_line")
    if ptr:
        ptr = weechat.hdata_pointer(weechat.hdata_get("line"), ptr, "data")
        if ptr:
            date = weechat.hdata_time(weechat.hdata_get("line_data"), ptr, "date")
            weechat.prnt("", "time of first line displayed = %s" % time.strftime("%F %T", time.localtime(int(date))))
----

==== hdata_hashtable

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

hdata を使って構造体に含まれるハッシュテーブル型変数の値を返す。

プロトタイプ:

[source,C]
----
struct t_hashtable *weechat_hdata_hashtable (struct t_hdata *hdata, void *pointer, const char *name);
----

引数:

* 'hdata': hdata へのポインタ
* 'pointer': WeeChat および plugin オブジェクトへのポインタ
* 'name': 変数名 (必ず"ハッシュテーブル型"であること); 配列の場合、"N|name"
  のように名前を指定することが可能。ここで N は配列のインデックス (1 番目は 0)、例: "2|name"

戻り値:

* ハッシュテーブル型変数の値 (ハッシュテーブルへのポインタ)

C 言語での使用例:

[source,C]
----
struct t_hdata *hdata = weechat_hdata_get ("buffer");
struct t_gui_buffer *buffer = weechat_buffer_search_main ();
struct t_hashtable *hashtable = weechat_hdata_hashtable (hdata, buffer, "local_variables");
weechat_printf (NULL, "%d local variables in core buffer",
                weechat_hashtable_get_integer (hashtable, "items_count"));
----

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

[source,python]
----
# プロトタイプ
hashtable = weechat.hdata_hashtable(hdata, pointer, name)

# 例
hdata = weechat.hdata_get("buffer")
buffer = weechat.buffer_search_main()
hash = weechat.hdata_hashtable(hdata, buffer, "local_variables")
weechat.prnt("", "local variables in core buffer:")
for key in hash:
    weechat.prnt("", "  %s == %s" % (key, hash[key]))
----

==== hdata_set

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

hdata の変数に新しい値を設定。

[NOTE]
変数の更新を許可している場合に、この関数呼び出して良いのは update
コールバックの中だけです (<<_hdata_new,weechat_hdata_new>>
と <<_hdata_update,weechat_hdata_update>> を参照)

プロトタイプ:

[source,C]
----
int weechat_hdata_set (struct t_hdata *hdata, void *pointer, const char *name, const char *value);
----

引数:

* 'hdata': hdata へのポインタ
* 'pointer': WeeChat および plugin オブジェクトへのポインタ
* 'name': 変数名 (許可されている型: 文字型、整数型、long
  型、文字列型、ポインタ型、時刻型)
* 'value': 変数の新しい値

戻り値:

* 成功した場合は 1、エラーが起きた場合は 0

C 言語での使用例:

[source,C]
----
weechat_hdata_set (hdata, pointer, "message", "test");
----

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

==== hdata_update

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

hdata 内のデータを更新。

プロトタイプ:

[source,C]
----
int weechat_hdata_update (struct t_hdata *hdata, void *pointer, struct t_hashtable *hashtable);
----

引数:

* 'hdata': hdata へのポインタ
* 'pointer': WeeChat および plugin オブジェクトへのポインタ
* 'hashtable': 更新する変数:
  キーは変数の名前、値は変数の新しい値
  (キーと値は文字列)、以下の特別なキーを使うことができます:
** キー `__create_allowed` (値は任意): 構造体の作製を許可する場合は
   1、許可しない場合は 0 を返す _(WeeChat バージョン 0.4.0 以上で利用可)_
** キー `__delete_allowed` (値は任意): 構造体の削除を許可する場合は
   1、許可しない場合は 0 を返す
** キー `__update_allowed` 、値は変数の名前: この変数の更新を許可する場合は
   1、許可しない場合は 0 を返す
** キー `__delete` (値は任意): 構造体を削除 (許可されている場合)

戻り値:

* 更新された変数の個数

C 言語での使用例:

[source,C]
----
/* 現在のバッファに表示されている最後のメッセージの時間を 1 時間前にする */

struct t_gui_lines *own_lines;
struct t_gui_line *line;
struct t_gui_line_data  *line_data;
struct t_hdata *hdata;
struct t_hashtable *hashtable;
char str_date[64];

own_lines = weechat_hdata_pointer (weechat_hdata_get ("buffer"), weechat_current_buffer (), "own_lines");
if (own_lines)
{
    line = weechat_hdata_pointer (weechat_hdata_get ("lines"), own_lines, "last_line");
    if (line)
    {
        line_data = weechat_hdata_pointer (weechat_hdata_get ("line"), line, "data");
        hdata = weechat_hdata_get ("line_data");
        hashtable = weechat_hashtable_new (8,
                                           WEECHAT_HASHTABLE_STRING,
                                           WEECHAT_HASHTABLE_STRING,
                                           NULL,
                                           NULL);
        if (hashtable)
        {
            snprintf (str_date, sizeof (str_date), "%ld", ((long int)weechat_hdata_time (hdata, line_data, "date")) - 3600);
            weechat_hashtable_set (hashtable, "date", str_date);
            weechat_hdata_update (hdata, line_data, hashtable);
            weechat_hashtable_free (hashtable);
        }
    }
}
----

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

[source,python]
----
# プロトタイプ
count = weechat.hdata_update(hdata, pointer, hashtable)

# 例: 現在のバッファに表示されている最後のメッセージの時間を 1 時間前にする
own_lines = weechat.hdata_pointer(weechat.hdata_get("buffer"), weechat.current_buffer(), "own_lines")
if own_lines:
    line = weechat.hdata_pointer(weechat.hdata_get("lines"), own_lines, "last_line")
    if line:
        line_data = weechat.hdata_pointer(weechat.hdata_get("line"), line, "data")
        hdata = weechat.hdata_get("line_data")
        weechat.hdata_update(hdata, line_data, {"date": str(weechat.hdata_time(hdata, line_data, "date") - 3600)})
----

==== hdata_get_string

_WeeChat バージョン 0.3.6 以上で利用可。_

hdata プロパティの文字列値を返す。

プロトタイプ:

[source,C]
----
const char *weechat_hdata_get_string (struct t_hdata *hdata, const char *property);
----

引数:

* 'hdata': hdata へのポインタ
* 'property': プロパティ名:
** 'var_keys': hdata に含まれる変数のキーのリストを含む文字列
   (フォーマット: "key1,key2,key3")
** 'var_values': hdata に含まれる変数の値のリストを含む文字列
   (フォーマット: "value1,value2,value3")
** 'var_keys_values': hdata に含まれる変数のキーと値のリストを含む文字列
   (フォーマット: "key1:value1,key2:value2,key3:value3")
** 'var_prev':
   構造体に含まれる変数の名前、構造体はリスト内の 1 つ前の要素へのポインタ
** 'var_next':
   構造体に含まれる変数の名前、構造体はリスト内の 1 つ後の要素へのポインタ
** 'list_keys': hdata に含まれるリストのキーのリストを含む文字列
   (フォーマット: "key1,key2,key3")
** 'list_values': hdata に含まれるリストの値のリストを含む文字列
   (フォーマット: "value1,value2,value3")
** 'list_keys_values': hdata に含まれるリストのキーと値のリストを含む文字列
   (フォーマット: "key1:value1,key2:value2,key3:value3")

戻り値:

* プロパティの文字列値

C 言語での使用例:

[source,C]
----
weechat_printf (NULL, "variables in hdata: %s", weechat_hdata_get_string (hdata, "var_keys"));
weechat_printf (NULL, "lists in hdata: %s", weechat_hdata_get_string (hdata, "list_keys"));
----

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

[source,python]
----
# プロトタイプ
value = weechat.hdata_get_string(hdata, property)

# 例
weechat.prnt("", "variables in hdata: %s" % weechat.hdata_get_string(hdata, "var_keys"))
weechat.prnt("", "lists in hdata: %s" % weechat.hdata_get_string(hdata, "list_keys"))
----

[[upgrade]]
=== アップグレード

WeeChat をアップグレードする (コマンド "/upgrade") 関数。

==== upgrade_new

アップグレード用のファイルを作成または読み込み。

プロトタイプ:

[source,C]
----
struct t_upgrade_file *weechat_upgrade_new (const char *filename, int write);
----

引数:

* 'filename': ファイルの名前 (WeeChat
  はこの名前に拡張子 ".upgrade" を追加します)
* 'write':
** '1': ファイルを作成 (書き込みモード、アップグレード前)
** '0': ファイルを読み込む (アップグレード後)

戻り値:

* アップグレードファイルへのポインタ

C 言語での使用例:

[source,C]
----
struct t_upgrade_file *upgrade_file = weechat_upgrade_new ("my_file", 1);
----

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

[source,python]
----
# プロトタイプ
upgrade_file = weechat.upgrade_new(filename, write)

# 例
upgrade_file = weechat.upgrade_new("my_file", 1)
----

==== upgrade_write_object

アップグレードファイルにオブジェクトを書き込む。

プロトタイプ:

[source,C]
----
int weechat_upgrade_write_object (struct t_upgrade_file *upgrade_file,
                                  int object_id,
                                  struct t_infolist *infolist);
----

引数:

* 'upgrade_file': アップグレードファイルへのポインタ
* 'object_id': オブジェクトの識別番号
* 'infolist': ファイルに書き込むインフォリスト

戻り値:

* 成功した場合は 1、エラーが起きた場合は 0

C 言語での使用例:

[source,C]
----
if (weechat_upgrade_write_object (upgrade_file, 1, &infolist))
{
    /* ok */
}
else
{
    /* error */
}
----

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

[source,python]
----
# プロトタイプ
rc = weechat.upgrade_write_object(upgrade_file, object_id, infolist)

# 例
weechat.upgrade_write_object(upgrade_file, 1, infolist)
----

==== upgrade_read

アップグレードファイルを読み込む。

プロトタイプ:

[source,C]
----
int weechat_upgrade_read (struct t_upgrade_file *upgrade_file,
                          int (*callback_read)(void *data,
                                               struct t_upgrade_file *upgrade_file,
                                               int object_id,
                                               struct t_infolist *infolist),
                          void *callback_read_data);
----

引数:

* 'upgrade_file': アップグレードファイルへのポインタ
* 'callback_read': アップグレードファイル内の各オブジェクトを読み込む際に呼び出す関数
  引数と戻り値:
** 'void *data': ポインタ
** 'struct t_upgrade_file *upgrade_file': アップグレードファイルへのポインタ
** 'int object_id': オブジェクトの識別番号
** 'struct t_infolist *infolist': オブジェクトの内容を含むインフォリスト
** 戻り値:
*** 'WEECHAT_RC_OK'
*** 'WEECHAT_RC_ERROR'
* 'callback_read_data': WeeChat が read
  コールバックを呼び出す際にコールバックに渡すポインタ

戻り値:

* 成功した場合は 1、エラーが起きた場合は 0

C 言語での使用例:

[source,C]
----
int
my_upgrade_read_cb (struct t_upgrade_file *upgrade_file,
                    int object_id,
                    struct t_infolist *infolist)
{
    /* read variables... */
    return WEECHAT_RC_OK;
}

weechat_upgrade_read (upgrade_file, &my_upgrade_read_cb, NULL);
----

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

[source,python]
----
# プロトタイプ
rc = weechat.upgrade_read(upgrade_file, callback_read, callback_read_data)

# 例
def my_upgrade_read_cb(upgrade_file, object_id, infolist):
    # read variables...
    return weechat.WEECHAT_RC_OK

weechat.upgrade_read(upgrade_file, "my_upgrade_read_cb", ""))
----

==== upgrade_close

アップグレードファイルを閉じる。

プロトタイプ:

[source,C]
----
void weechat_upgrade_close (struct t_upgrade_file *upgrade_file);
----

引数:

* 'upgrade_file': アップグレードファイルへのポインタ

C 言語での使用例:

[source,C]
----
weechat_upgrade_close (upgrade_file);
----

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

[source,python]
----
# プロトタイプ
weechat.upgrade_close(upgrade_file)

# 例
weechat.upgrade_close(upgrade_file)
----