このマニュアルは WeeChat チャットクライアントについて説明しており、WeeChat の一部です。

このマニュアルの最新版は以下のページを参照してください: https://weechat.org/doc

1. イントロダクション

WeeChat (Wee Enhanced Environment for Chat) はフリー、高速、軽量な 多くのオペレーティングシステムで動くチャットクライアントです。

このマニュアル文書は以下のスクリプト言語を利用して WeeChat 用のスクリプトを製作する方法を解説しています:

  • python

  • perl

  • ruby

  • lua

  • tcl

  • guile (scheme)

Note
この文書に含まれるほぼすべての例は Python で書かれていますが API は他の言語でも共通です。

2. WeeChat のスクリプト

2.1. 言語仕様

2.1.1. Python

  • import weechat を使うことは必須です。

  • python では print* 系の関数は prnt* と呼ばれます (print は予約済みキーワードなので)。

  • 関数は weechat.xxx(arg1, arg2, ...) のように呼び出してください。

2.1.2. Perl

  • 関数は weechat::xxx(arg1, arg2, ...); のように呼び出してください。

2.1.3. Ruby

  • weechat_init を定義して、内部で register を呼び出してください。

  • 関数は Weechat.xxx(arg1, arg2, ...) のように呼び出してください。

  • Ruby では関数に渡せる引数の数が最大 15 個に制限されているため、Weechat.config_new_option 関数はコールバック用の引数群を 6 個の文字列からなる 1 個の配列で受け取ります (3 個のコールバック + 3 個のデータ文字列)、したがって Weechat.config_new_option 関数を呼び出すには以下のようにしてください:

2.1.4. Lua

  • 関数は weechat.xxx(arg1, arg2, ...) のように呼び出してください。

2.1.5. Tcl

  • 関数は weechat::xxx arg1 arg2 ... のように呼び出してください。

2.1.6. Guile (scheme)

  • 関数は (weechat:xxx arg1 arg2 ...) のように呼び出してください。

  • 以下の関数は引数のリストをひとつだけ取ります。 (他の関数のように多くの引数を取れません)、 この理由は引数の個数が Guile で利用できる引数の数を超えるからです。

    • config_new_section

    • config_new_option

    • bar_new

2.2. 関数の登録

全ての WeeChat スクリプトは WeeChat に自分自身を "登録" し、登録はスクリプトの最初で行われなければいけません。

プロトタイプ:

引数:

  • name: 文字列型、スクリプトの内部名

  • author: 文字列型、作者名

  • version: 文字列型、スクリプトのバージョン

  • license: 文字列型、スクリプトのライセンス

  • description: 文字列型、スクリプトの短い説明

  • shutdown_function: 文字列型、スクリプトがアンロードされた際に呼び出される関数の名前 (空文字列でも可)

  • charset: 文字列型、スクリプトの文字コード (UTF-8 はデフォルトの文字コードなので、スクリプトが UTF-8 で書かれている場合、空文字列を指定してください)

各言語で書かれたスクリプトの例:

  • python:

  • perl:

  • ruby:

  • lua:

  • tcl:

  • guile (scheme):

2.3. スクリプトのロード

スクリプトをロードするには "script" プラグインを使うことを推奨します。例:

/script load script.py
/script load script.pl
/script load script.rb
/script load script.lua
/script load script.tcl
/script load script.scm

プログラミング言語ごとの固有コマンドを利用することもできます:

/python load python/script.py
/perl load perl/script.pl
/ruby load ruby/script.rb
/lua load lua/script.lua
/tcl load tcl/script.tcl
/guile load guile/script.scm

WeeChat の開始時にスクリプトを自動ロードするには language/autoload ディレクトリ内にリンクを作ってください。

例えば Python の場合:

$ cd ~/.weechat/python/autoload
$ ln -s ../script.py
Note
/script install コマンドでスクリプトをインストールした場合、autoload ディレクトリ内にリンクが自動的に作成されます。

3. C API との違い

スクリプト API は C プラグイン API とほぼ同じです。API に含まれる各関数の詳細については、WeeChat プラグイン API リファレンス をご覧ください: プロトタイプ、引数、戻り値、例

プラグインスクリプト の違いを理解することは重要です: プラグイン とはコンパイル済みバイナリファイルで /plugin コマンドを使ってロードします、これに対して スクリプト とはテキストファイルで例えば python プラグインであれば /python コマンドを使ってロードします。

例えば test.py スクリプトが WeeChat API 関数を呼び出す場合、以下の順に呼び出されます:

               ┌──────────────────────┐        ╔══════════════════╗
               │     python plugin    │        ║  WeeChat "core"  ║
               ├────────────┬─────────┤        ╟─────────┐        ║
test.py ─────► │ script API │  C API  │ ─────► ║  C API  │        ║
               └────────────┴─────────┘        ╚═════════╧════════╝

WeeChat が test.py スクリプトで定義されたコールバックを呼び出す場合、順番は逆になります:

╔══════════════════╗        ┌──────────────────────┐
║  WeeChat "core"  ║        │     python plugin    │
║        ┌─────────╢        ├─────────┬────────────┤
║        │  C API  ║ ─────► │  C API  │ script API │ ─────► test.py
╚════════╧═════════╝        └─────────┴────────────┘

3.1. ポインタ

ご存知かもしれませんが、スクリプトには本当の意味での "ポインタ" はありません。このため API 関数がポインタを返す場合、スクリプトでは文字列に変換されます。

例えば、関数がポインタ 0x1234ab56 を返した場合、スクリプトは "0x1234ab56" という文字列を受け取ることになります。

API 関数の引数にポインタを与える場合、スクリプトではポインタを文字列型として渡さなければいけません。C API 関数を呼び出す前に C プラグインがこれを本来のポインタ型に変換します。

空文字列や "0x0" を使うことも許されています。これらは C で言うところの NULL と解釈されます。例えば、データをコアバッファ (WeeChat メインバッファ) に表示する場合、以下のようになります:

Warning
多くの関数ではスピードの関係で、WeeChat はポインタの値が正当なものか否かの確認を行いません。 ポインタの正当性を確認することはプログラマが行わなければいけません。 不正なポインタを利用した場合、細かなクラッシュレポートを目にすることになるでしょう ;)

3.2. コールバック

ほとんど全ての WeeChat コールバックは WEECHAT_RC_OK 又は WEECHAT_RC_ERROR を返さなければいけません (modifier コールバックは例外で、これは文字列を返します)。

C コールバックはポインタ型の "data" 引数を利用します。スクリプト API では、"data" は文字列型で任意の値を取れます (ポインタ型ではありません)。

各プログラミング言語でコールバックを利用する例:

  • python:

  • perl:

  • ruby:

  • lua:

  • tcl:

  • guile (scheme):

4. スクリプト API

API に含まれる関数の詳しい情報は WeeChat プラグイン API リファレンス をご覧ください。.

4.1. 関数

スクリプト API に含まれる関数のリスト:

カテゴリ 関数

一般

register

プラグイン

plugin_get_name

設定

charset_set, iconv_to_internal, iconv_from_internal, gettext, ngettext,
strlen_screen, string_match, string_has_highlight, string_has_highlight_regex, string_mask_to_regex, string_remove_color, string_is_command_char, string_input_for_buffer, string_eval_expression

ディレクトリ操作

mkdir_home, mkdir, mkdir_parents

ソート済みリスト

list_new, list_add, list_search, list_search_pos, list_casesearch, list_casesearch_pos, list_get, list_set, list_next, list_prev, list_string, list_size, list_remove, list_remove_all, list_free

設定ファイル

config_new, config_new_section, config_search_section, config_new_option, config_search_option,
config_string_to_boolean, config_option_reset, config_option_set, config_option_set_null, config_option_unset, config_option_rename, config_option_is_null, config_option_default_is_null,
config_boolean, config_boolean_default, config_integer, config_integer_default, config_string, config_string_default, config_color, config_color_default,
config_write_option, config_write_line, config_write, config_read, config_reload,
config_option_free, config_section_free_options, config_section_free, config_free,
config_get, config_get_plugin, config_is_set_plugin, config_set_plugin, config_set_desc_plugin, config_unset_plugin

キー割り当て

key_bind, key_unbind

表示

prefix, color, print (for python: prnt), print_date_tags (for python: prnt_date_tags), print_y (for python: prnt_y), log_print

フック

hook_command, hook_command_run, hook_timer, hook_fd, hook_process, hook_process_hashtable, hook_connect, hook_print, hook_signal, hook_signal_send, hook_hsignal, hook_hsignal_send, hook_config, hook_completion, hook_completion_list_add, hook_modifier, hook_modifier_exec, hook_info, hook_info_hashtable, hook_infolist, hook_focus, hook_set, unhook, unhook_all

バッファ

buffer_new, current_buffer, buffer_search, buffer_search_main, buffer_clear, buffer_close, buffer_merge, buffer_unmerge, buffer_get_integer, buffer_get_string, buffer_get_pointer, buffer_set, buffer_string_replace_local_var, buffer_match_list

ウィンドウ

current_window, window_search_with_buffer, window_get_integer, window_get_string, window_get_pointer, window_set_title

ニックネームリスト

nicklist_add_group, nicklist_search_group, nicklist_add_nick, nicklist_search_nick, nicklist_remove_group, nicklist_remove_nick, nicklist_remove_all, nicklist_group_get_integer, nicklist_group_get_string, nicklist_group_get_pointer, nicklist_group_set, nicklist_nick_get_integer, nicklist_nick_get_string, nicklist_nick_get_pointer, nicklist_nick_set

バー

bar_item_search, bar_item_new, bar_item_update, bar_item_remove, bar_search, bar_new, bar_set, bar_update, bar_remove

コマンド

command

情報

info_get, info_get_hashtable

情報リスト

infolist_new, infolist_new_item, infolist_new_var_integer, infolist_new_var_string, infolist_new_var_pointer, infolist_new_var_time,
infolist_get, infolist_next, infolist_prev, infolist_reset_item_cursor,
infolist_fields, infolist_integer, infolist_string, infolist_pointer,
infolist_time, infolist_free

hdata

hdata_get, hdata_get_var_offset, hdata_get_var_type_string, hdata_get_var_array_size, hdata_get_var_array_size_string, hdata_get_var_hdata, hdata_get_list, hdata_check_pointer, hdata_move, hdata_search, hdata_char, hdata_integer, hdata_long, hdata_string, hdata_pointer, hdata_time, hdata_hashtable, hdata_update, hdata_get_string

アップグレード

upgrade_new, upgrade_write_object, upgrade_read, upgrade_close

4.2. 定数

スクリプト API に含まれる定数のリスト:

カテゴリ 定数

リターンコード

WEECHAT_RC_OK, WEECHAT_RC_OK_EAT, WEECHAT_RC_ERROR

設定ファイル

WEECHAT_CONFIG_READ_OK, WEECHAT_CONFIG_READ_MEMORY_ERROR, WEECHAT_CONFIG_READ_FILE_NOT_FOUND, WEECHAT_CONFIG_WRITE_OK, WEECHAT_CONFIG_WRITE_ERROR, WEECHAT_CONFIG_WRITE_MEMORY_ERROR,
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, WEECHAT_CONFIG_OPTION_UNSET_OK_NO_RESET, WEECHAT_CONFIG_OPTION_UNSET_OK_RESET, WEECHAT_CONFIG_OPTION_UNSET_OK_REMOVED, WEECHAT_CONFIG_OPTION_UNSET_ERROR

ソート済みリスト

WEECHAT_LIST_POS_SORT, WEECHAT_LIST_POS_BEGINNING, WEECHAT_LIST_POS_END

ホットリスト

WEECHAT_HOTLIST_LOW, WEECHAT_HOTLIST_MESSAGE, WEECHAT_HOTLIST_PRIVATE, WEECHAT_HOTLIST_HIGHLIGHT

プロセスのフック

WEECHAT_HOOK_PROCESS_RUNNING, WEECHAT_HOOK_PROCESS_ERROR

接続のフック

WEECHAT_HOOK_CONNECT_OK, WEECHAT_HOOK_CONNECT_ADDRESS_NOT_FOUND, WEECHAT_HOOK_CONNECT_IP_ADDRESS_NOT_FOUND, WEECHAT_HOOK_CONNECT_CONNECTION_REFUSED, WEECHAT_HOOK_CONNECT_PROXY_ERROR, WEECHAT_HOOK_CONNECT_LOCAL_HOSTNAME_ERROR, WEECHAT_HOOK_CONNECT_GNUTLS_INIT_ERROR, WEECHAT_HOOK_CONNECT_GNUTLS_HANDSHAKE_ERROR, WEECHAT_HOOK_CONNECT_MEMORY_ERROR, WEECHAT_HOOK_CONNECT_TIMEOUT, WEECHAT_HOOK_CONNECT_SOCKET_ERROR

シグナルのフック

WEECHAT_HOOK_SIGNAL_STRING, WEECHAT_HOOK_SIGNAL_INT, WEECHAT_HOOK_SIGNAL_POINTER

5. 良くあるタスク

この章ではいくつかの良くあるタスクを例を交えて紹介します。ここでは API の一部の機能を使っています。完全なリファレンスは WeeChat プラグイン API リファレンス をご覧ください。

5.1. バッファ

5.1.1. メッセージの表示

WeeChat コアバッファに対して操作する場合、空文字列を使うことが多いです。他のバッファに対して操作する場合には、ポインタ (文字列型、ポインタ を参照) を与える必要があります。

例:

Note
Print 関数は Perl/Ruby/Lua/Tcl では print で、Python では prnt です。

5.1.2. バッファにテキストを送信

テキストやコマンドをバッファに送信できます。これはテキストやコマンドをタイプして [Enter] を押すことに対応します。

例:

5.1.3. 新規バッファの作成

スクリプトを使って新しいバッファを作成し、このバッファにメッセージを表示させることができます。

2 つのコールバックを定義できます (任意): データの入力時に呼び出されるもの (バッファでテキストを入力して [Enter] を押した時) と、バッファが閉じられたときに呼び出されるもの (例えば /buffer close した時等) です。

例:

5.1.4. バッファプロパティ

文字列、整数、ポインタ型のバッファプロパティを読むことができます。

例:

バッファに対するローカル変数を追加、読み込み、削除することができます:

バッファに対するローカル変数を見るには、WeeChat で以下のコマンドを実行してください:

/buffer localvar

5.2. フック

5.2.1. 新しいコマンドの追加

カスタムコマンドを追加するには hook_command を使ってください。 追加したコマンドに対してカスタム補完テンプレートを定義できます。

例:

上で定義したコマンドを WeeChat で以下のように使うことができます:

/help myfilter

/myfilter arguments...

5.2.2. タイマーの追加

タイマーを追加するには hook_timer を使ってください。

例:

5.2.3. バックグラウンドプロセスの実行

hook_process を使ってバックグラウンドプロセスを実行できます。 コールバックはデータの準備が整った時点で呼び出されます。複数回呼び出されることもあります。

コールバックの最後の呼び出しでは rc が 0 か正の値に設定されています。これはコマンドのリターンコードになります。

例:

5.2.4. URL 転送

バージョン 0.3.7 に含まれる新機能

URL をダウンロードする (又は URL にポストする) には、関数 hook_process 又は URL 転送にオプションが必要な場合は hook_process_hashtable を使わなければいけません。

オプション無しの URL 転送の例: HTML ページの内容はコールバックの "out" 引数 (プロセスの標準出力) を通して渡されます。

Tip
WeeChat に関して利用できる情報は全て https://weechat.org/dev/info にあります

オプション有りの URL 転送の例: 最新の WeeChat 開発パッケージをファイル /tmp/weechat-devel.tar.gz にダウンロード:

URL 転送に関するより詳しい情報と利用可能なオプションを見るには、 WeeChat プラグイン API リファレンスhook_processhook_process_hashtable をご覧ください。

5.3. 設定 / オプション

5.3.1. スクリプトのオプションを設定

オプションが設定されているかどうかを確認するには config_is_set_plugin 関数、オプションを設定するには config_set_plugin 関数を使います。

例:

5.3.2. 変更の検出

ユーザがスクリプトオプションを変更したことを検出するには hook_config を使わなければいけません。

例:

5.3.3. WeeChat オプションの読み込み

config_get 関数はオプションへのポインタを返します。オプションの型に従って config_stringconfig_booleanconfig_integerconfig_color を呼び出さなければいけません。

5.4. IRC

5.4.1. メッセージのキャッチ

メッセージを受信すると IRC プラグインは 2 つのシグナルを送信します (xxx は IRC 内部サーバ名で、yyy は JOIN、QUIT、PRIVMSG、301 等の IRC コマンド名です):

xxxx,irc_in_yyy

メッセージの処理が行われる前に送信されるシグナル

xxx,irc_in2_yyy

メッセージの処理が行われた後に送信されるシグナル

5.4.2. メッセージの修正

メッセージを受信すると IRC プラグインは "irc_in_xxx" ("xxx" は IRC コマンド) と呼ばれる "modifier" を送信します。メッセージを修正するにはこのシグナルを使います。

Warning
不正なメッセージは WeeChat をクラッシュさせ、深刻な問題を引き起こします!

5.4.3. メッセージの構文解析

バージョン 0.3.4 の新機能

"irc_message_parse" と呼ばれる info_hashtable を使って IRC メッセージを構文解析できます。

5.5. 情報

5.5.1. WeeChat のバージョン

バージョンを確認する最良の方法は "version_number" を参照し、16 進数のバージョン番号と整数値比較することです。

例:

Note
バージョン 0.3.1.1 以下では info_get("version_number") は空文字列を返すため、値が空でないことを確認しなければいけません。

文字列でバージョンを使うには:

5.5.2. その他の情報

5.6. 情報リスト

5.6.1. 情報リストの読み込み

WeeChat や他のプラグインによって作られた情報リストを読み込むことができます。

例:

Important
WeeChat は自動的にメモリを解放しません、情報リストによって使われたメモリを解放するには、infolist_free を呼び出すことを忘れないでください。