このマニュアルは 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, |
ディレクトリ操作 |
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, |
キー割り当て |
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, |
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_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_process
と hook_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_string
、config_boolean
、config_integer
、config_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
を呼び出すことを忘れないでください。 |