This file describes Riece.

Copyright (C) 2003,2004 Daiki Ueno.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts.  A copy of the license is included in the section entitled "GNU Free Documentation License".

Riece user's manual
*******************

Riece は Emacs で IRC (Internet Relay Chat) に参加するためのプログラムです。

Overview
********

Riece は、長い間メンテナンス不可能な状態にあった Liece のコードを完全に書き直したものです。ユーザインターフェースの大部分は Liece のものを踏襲しています。

現在のところ IRC クライアントとしての機能は十分ではありませんが、Liece にはない特長がいくつかあります。以下にそれらの一部を挙げます。

  * 複数の IRC サーバに同時に接続可能

  * アドオンにより機能の追加や取り外しが可能

  * 他の elisp パッケージに依存しないため、インストールが簡単

  * 設定が簡単で、前回起動時の設定を記録・復元する仕組みを提供

  * 段階的な操作説明書(現在は日本語のみ)が附属

  * 最新の IRC のクライアントプロトコル (RFC2812) に準拠

より詳しい情報は、以下のページを御覧ください。

  * http://www.nongnu.org/riece/

  * http://wiliki.designflaw.org/index.cgi?Riece&l=jp

  * http://www.unixuser.org/~ueno/liece/

Getting started
***************

Required Environments
=====================

次に挙げる環境で動作を確認しています。

  * Emacs 20.7 以上

  * XEmacs 21.4 以上

Installation
============

Riece の最新版は、 http://wiliki.designflaw.org/riece.cgi で配布しています。展開したら、以下のコマンドを実行することで手元の環境にインストールできます

     ./configure
     make
     make install

XEmacs のパッケージとしてインストールする場合には以下のようにします。

     ./configure --with-xemacs[=xemacs-21.4.15]
     make package
     make install-package

XEmacs のパッケージとしてインストールした場合には必要ありませんが、 M-x riece で起動するためには、autoload の設定を御自分の Emacs の設定ファイルに加える必要があります。

     (autoload 'riece "riece" "Start Riece" t)

Startup file
============

この章では、設定ファイルについて解説します。

試しに使ってみる場合には、特に何も設定する必要はありません。この章は読み飛ばしても構いません。

Riece は設定ファイルを変数 riece-directory で指示されるディレクトリ (デフォルトは ~/.riece/) から読み込みます。このディレクトリには以下の 2 つの設定ファイルが配置されます。

riece-saved-variables-file
     前回のセッションで更新された設定が自動的に保存されます(デフォルトは ~/.riece/save)

riece-variables-file
     ユーザに固有の設定を記述します(デフォルトは ~/.riece/init)

起動時には、最初に riece-saved-variables-file を、次に riece-variables-file を読み込みます。つまり、 ~/.riece/save に自動的に保存された内容は、~/.riece/init に記述された内容で上書きされます。

Basic usage
***********

M-x riece とすることで起動します。サーバ名を聞かれるので答えます。接続可能な IRC サーバは各 IRC ネットワーク毎に異なりますが、大抵は Web ページに一覧がまとめてあることが多いでしょう。

  * http://irc.kyoto-u.ac.jp

  * http://freenode.net

もしニックネームが既に使用されている場合、別のニックネームの入力を促されます。ニックネームの初期値は riece-nickname で設定します。デフォルトでは、ユーザのログイン名がそのまま使われます。

無事に接続できたなら、次はチャンネルに参加して会話をしてみましょう。 C-c j とタイプすると、チャンネル名を尋ねられるので、適当なチャンネル名を入力しましょう。たとえば IRCnet には #Liece というチャンネルがあるので、テストにお使いください。

チャンネルに入ることができたら、文章を入力してリターンキーを押すと発言することができます。他の人の会話は画面右上のバッファに表示されます。

Windows
=======

デフォルトの設定では、チャンネルに入ると、下の図に示すような 5 つのウィンドウからなる画面に切り替わります。

     +-----+-----------------+
     |     |                 |
     |     |                 |
     | (1) |       (2)       |
     |     |                 |
     |     |                 |
     +-----+-----------------+
     |     |       (4)       |
     |     +-----------------+
     | (3) |                 |
     |     |       (5)       |
     |     |                 |
     +-----+-----------------+

これらの各ウィンドウに表示されるバッファの役割は以下の通りです。

 1. ユーザリストバッファ (*Users XXX*)。チャンネルにいるユーザの一覧が表示されます。

 2. チャンネルバッファ (*Channel XXX*)。チャンネル内の会話が表示されます。

 3. チャンネルリストバッファ (*Channels*)。参加しているチャンネルの一覧が表示されます。

 4. コマンドバッファ (*Commands*)。文章やコマンドを送信するために使います。

 5. アザーズバッファ (*Others*)。現在のチャンネル以外の会話が流れます。

Indicators
==========

コマンドバッファやチャンネルバッファのモードラインの左端には、自分の現在の状態を示す印が表示されます。

     Riece: --- ueno #Liece [n]

ここで、--- の部分には左から順に以下の意味があります。

 1. 離席状態 (離席していれば A)

 2. オペレータ状態 (IRC オペレータであれば O)

 3. チャンネルバッファ、またはダイアログバッファのスクロール禁止状態 (完全に禁止していれば F、自分の次回の発言まで禁止しているのであれば f)

Commands
========

文章を入力したバッファは、コマンドバッファと呼ばれ、コマンドバッファからは様々なコマンドを発行することができます。以下に一部を挙げます。

IRC commands
------------

RET
     文章を送ります(riece-command-enter-message)

C-RET
     文章を NOTICE として送ります(riece-command-enter-message-as-notice)

C-c j
     チャンネルに参加します(riece-command-join)

C-c C-p
     チャンネルから離脱します(riece-command-part)

C-c p
     宛先を指定して現在の行を送ります(riece-command-enter-message-to-user)

C-c q
     IRC をやめます(riece-command-quit)

C-c n
     自分のニックネームを変更します(riece-command-change-nickname)

C-c f
     ユーザの情報を調べます(riece-command-finger)

C-c C-k
     ユーザをチャンネルから蹴り出します(riece-command-kick)

C-c i
     ユーザをチャンネルに招待します(riece-command-invite)

C-c l
     パターンに対して LIST を発行します(riece-command-list)

C-c C-n
     パターンに対して NAMES を発行します(riece-command-names)

C-c w
     パターンに対して WHO を発行します(riece-command-who)

C-c t
     チャンネルのトピックを設定します(riece-command-topic)

C-c C-m
     チャンネルのモードを設定します(riece-command-change-mode)

C-c o
     ユーザにオペレータ権限を与えます。前置引数 (C-u) を与えると、ユーザから発言権を奪います(riece-command-set-operators)

C-c v
     ユーザに発言権を与えます。前置引数 (C-u) を与えると、ユーザから発言権を奪います(riece-command-set-speakers)

C-c V
     Riece のバージョンを表示します。前置引数 (C-u) を与えると、より詳細な情報を表示します。

C-c /
     生の IRC コマンドを送ります(riece-command-raw)

Window manipulating commands
----------------------------

C-c r
     ウィンドウを再描画します(riece-command-configure-windows)

C-c C-j
     次のチャンネルに移ります(riece-command-next-channel)

C-c <
     前のチャンネルに移ります(riece-command-previous-channel)

C-c >
     次のチャンネルに移ります(riece-command-next-channel)

C-c ^
     アドオンの一覧を表示します(riece-command-list-addons)

C-c 数字
     N番目のチャンネルに移動します(riece-command-switch-to-channel-by-number)

C-c C-c 数字
     N + 10番目のチャンネルに移動します(riece-command-switch-to-channel-by-number)

C-c $
     チャンネルバッファ、またはダイアログバッファのビューを下端まで移動します(riece-command-end-of-buffer)

C-c SPC
     チャンネルバッファ、またはダイアログバッファを上方向にスクロールします(riece-command-scroll-up)

C-c DEL
     チャンネルバッファ、またはダイアログバッファを下方向にスクロールします(riece-command-scroll-down)

Status toggle commands
----------------------

C-c C-t c
     チャンネルバッファの表示・非表示を切り替えます(riece-command-toggle-channel-buffer-mode)

C-c C-t C
     チャンネルリストバッファの表示・非表示を切り替えます(riece-command-toggle-channel-list-buffer-mode)

C-c C-t u
     ユーザリストバッファの表示・非表示を切り替えます(riece-command-toggle-user-list-buffer-mode)

C-c C-t f
     チャンネルバッファ、またはダイアログバッファを凍結(スクロールを禁止)します(riece-command-toggle-freeze)

C-c C-t o
     チャンネルバッファ、またはダイアログバッファを、自分が発言するまで凍結します(riece-command-toggle-own-freeze)

C-c C-t a
     自分の離席状態を切り替えます(riece-command-toggle-away)

Connecting to multiple servers
==============================

Riece の大きな特長に、複数のサーバに同時に接続する機能があります。

新たなサーバに接続し、そのサーバ上のチャンネルに参加する手順は以下のようになります。

 1. C-c O (riece-command-open-server) とします。サーバ名を聞かれるので答えます。

 2. C-c j (riece-command-join) でチャンネルに参加します。ここで、チャンネル名の後に空白で区切ってサーバ名を続けます。空白を入力するには、 C-q を使います。たとえば、サーバ irc6 上の #Liece に参加するには C-c j #Liece C-q SPC irc6 とタイプすることになります。

チャンネルに入らずにコマンドを送るには、C-c M (riece-command-universal-server-name-argument) が便利です。

サーバとの接続に関するコマンドは以下の通りです。

C-c O
     別のサーバに接続します(riece-command-open-server)

C-c C
     サーバとの接続を切断します(riece-command-close-server)

C-c M
     特定のサーバに対して、続くコマンドを発行します(riece-command-universal-server-name-argument)

Advanced usage
**************

この章では、もっと進んだ使い方を解説します。

Server settings
===============

起動時にデフォルトで接続する IRC サーバは riece-server で指定します。

ここで riece-server は文字列であり、そのフォーマットは次のようになります。

      "<サーバのホスト名>:<ポート番号>[:<パスワード>]"

riece-server-alist を適切に設定すると、キーワードを使って、より詳細な指定が可能になります。以下は筆者の設定から抜き出した例です。

     (setq riece-server-alist
           '(("irc6" :host "irc6.nara.wide.ad.jp")
             ("plum" :host "localhost" :service 26667
              :function relay-open-network-stream))
           riece-server "irc6")

riece-server-alist の各要素の意味は以下の通りです。

  * irc6 という略記名で irc6.nara.wide.ad.jp に接続

  * plum という略記名で relay-open-network-stream を通じて (SSH 経由で) 接続

指定可能なキーワードは以下の通りです。

:host
     サーバのホスト名または IP アドレス

:service
     サーバのサービス名またはポート番号 (デフォルトは 6667)

:nickname
     接続時のニックネーム

:username
     接続時のユーザネーム

:password
     接続時のパスワード

:function
     接続用関数

:coding
     コーディングシステム (デフォルトは riece-default-coding-system の値)

Add-ons
=======

Riece では、ユーザが新たな機能を追加し、自由に取り外しできるよう、アドオンと呼ばれる機構を用意しています。アドオンは通常の elisp モジュールを拡張したもので、ロードの順番だけではなく、初期化処理の依存関係も記述することができます。

現在、以下のモジュールがアドオンとして実装されています：

riece-highlight
     バッファの色付け

riece-ctcp
     CTCP (Client To Client Protocol)

riece-url
     会話に現れた URL の収集

riece-unread
     発言のあったチャンネルに!マークをつける

riece-rdcc
     DCC (Direct Client to Client protocol) によるファイル転送 (Ruby による実装)

riece-ndcc
     DCC (Direct Client to Client protocol) によるファイル転送 (Emacs 21.3 の make-network-process による実装)

riece-mini
     ミニバッファのみで IRC をする

riece-log
     会話のログの収集

riece-doctor
     doctor.el と連携して精神科医になりすます

riece-alias
     チャンネル名やニックネームの別名を定義

riece-skk-kakutei
     SKK 使用時に変換モードの印を発言から取り除く

riece-guess
     色々な方法で移動先のチャンネルを推測

riece-history
     チャンネル移動の履歴管理

riece-button
     ボタンやポップアップメニューの表示

riece-keyword
     キーワードの強調表示

riece-menu
     メニューバーにメニューを登録

riece-async
     Emacs が busy or suspend 状態になることに備え、 PING に応答する local proxy 経由で IRC サーバに接続

riece-lsdb
     アドレス帳 LSDB (Lovely Sister Database) http://lsdb.sourceforge.jp と連携

riece-xface
     ユーザリストバッファにユーザの X-Face を表示

riece-ctlseq
     コントロールシーケンス (^B など) による強調表示

これらのうち、riece-highlight と riece-ctcp、 riece-url、 riece-unread、 riece-guess、 riece-history、 riece-button、riece-menu はデフォルトで組み込まれています。

アドオンを組み込むには riece-addons を設定します。たとえば riece-alias を組み込む場合には、~/.riece/init.el に以下のように記述します。

     (add-to-list 'riece-addons 'riece-alias)

Tips
****

この章では、よく聞かれる質問に対する答えや、便利な設定を紹介します。

チャンネル名「#ほげ:*.jp」を「%ほげ」と略記したい
============================

以下の行を ~/.riece/init.el に追加します：

     (add-to-list 'riece-addons 'riece-alias)

直前にいたチャンネルに戻りたい
===============

以下の行を ~/.riece/init.el に追加することで、 C-c g で履歴を辿りつつ移動できます。

     (add-hook 'riece-guess-channel-try-functions
               'riece-guess-channel-from-history)

発言があるとバッファがスクロールするのを止めたい
========================

C-c C-t f です。(irchat では C-c C-f) "t"oggle "f"reeze と覚えましょう。

派手な装飾を抑制したい
===========

riece-addons から、色付け (riece-highlight)、ボタン (riece-button)、アイコン (riece-icon) を除きます。

たとえば色付けをやめたいのであれば、以下の行を ~/.riece/init.el に追加します：

     (setq riece-addons (delq 'riece-highlight riece-addons))

キーワードに反応して音を鳴らしたい
=================

XEmacs では、以下の設定を ~/.riece/init.el に加えることで、"ほげ" や "ふが" に反応して効果音(この例では、カッコーの鳴き声)を鳴らすことができます。

     (load-default-sounds)
     (setq riece-keywords '("ほげ" "ふが"))
     (add-hook 'riece-keyword-notify-functions
               (lambda (keyword message) (play-sound 'cuckoo)))

Emacs の場合は,以下の設定を ~/.riece/init.el に加えることで, "ほげ" や "ふが" に反応して音を鳴らすことができます。

     (defun cuckoo ()
       "play cuckoo.au"
       (call-process "play" nil 0 t
                     ".../cuckoo.au"))
       (setq riece-keywords '("ほげ" "ふが"))
       (add-hook 'riece-keyword-notify-functions
                 (lambda (keyword message) (cuckoo)))

効果音ではなくシンプルにビープ音を鳴らしたい場合は、以下の設定を ~/.riece/init.el に加えます。

     (setq riece-keywords '("ほげ" "ふが"))
     (add-hook 'riece-keyword-notify-functions
               (lambda (keyword message) (ding)))

SKK を使っていて、変換モードの印 (▽) を送信したくない
===============================

以下の行を ~/.riece/init.el に追加します：

     (add-to-list 'riece-addons 'riece-skk-kakutei)

チャンネルの番号を固定したい
==============

以下の行を ~/.riece/init.el に追加します：

     (setq riece-default-channel-binding
          '("#Liece" "#emacsen" nil "#debianjp"))

1: #Liece, 2: #emacsen, 4: #debianjp のように割当てられます。nil はデフォルトでは自動割当ての対象にならないこと意味し、新たなチャンネルに参加した場合、そのチャンネルが 3 番目のチャンネルとして扱われます。

起動時にパスワードつきのチャンネルに参加したい
=======================

以下の行を ~/.riece/init.el に追加します：

     (setq riece-startup-channel-list
          '(("#secret" "password") "#Liece"))

複数のサーバ上のチャンネルに参加するには、 riece-startup-server-list も併せて設定する必要があります。

例として、riece-server と riece-server-alist を以下のように設定したとします。

     (setq riece-server "ircnet"
           riece-server-alist '(("ircnet" :host "irc6.nara.wide.ad.jp")
                                ("freenode" :host "irc.ipv6.freenode.net")))

この場合、デフォルトでは "ircnet" だけに接続しますが、 riece-startup-server-list を以下のように設定することで、 "freenode" にも接続するようになります。

     (setq riece-startup-server-list '("freenode"))

HTTP プロキシ越しに IRC サーバに接続したい
==========================

relay.el と connect.c を使うと、 HTTP プロキシを介して IRC サーバに接続することができます。

relay.el
     http://www.imasy.or.jp/~gotoh/lisp/relay.el

connect.c
     http://www.imasy.or.jp/~gotoh/ssh/connect.html

たとえば、"proxy.example.com:8080" 経由で irc.tokyo.wide.ad.jp に接続する場合には、以下の行を ~/.riece/init.el に追加します：

     (require 'relay)
     (setq relay-command-alist (cons '("^irc\.tokyo\.wide\.ad\.jp$"
                                       "connect" "-H" "proxy.example.com:8080"
                                       host service)
                                     relay-command-alist)
           riece-server-alist (cons '("proxy-tokyo" :host "irc.tokyo.wide.ad.jp"
                                      :function relay-open-network-stream)
                                    riece-server-alist))

IRC ログをファイルに保存したい
=================

以下の行を ~/.riece/init.el に追加します：

     (add-to-list 'riece-addons 'riece-log)

ログファイルはデフォルトでは ~/.riece/log の下にサーバ名、チャンネル名のディレクリが作成され、その中に日にち毎に保存されます。ただしデフォルトのサーバの場合は、サーバ名のディレクトリは省略されます。

US-ASCII 以外のディレクトリ名が文字化けするという人は、 file-name-coding-system の値を適切に設定するか、あるいは riece-log-directory-map でチャンネル名と保存先のディレクトリ名との対応リストを以下の例のように、US-ASCII のみを使用したディレクトリ名になるように設定する事で回避出来ます：

     (setq riece-log-directory-map '(("#りーす" . "riece")))

Development
***********

開発者募集中。

CVS
===

Riece の開発は CVS を利用して行っています。CVS サーバから最新のスナップショットを取得するには以下のようにします。

 1. CVS サーバへのログイン

          cvs -d :pserver:anonymous@cvs.m17n.org:/cvs/root login
          CVS password: [CR] # NULL string

 2. モジュールのチェックアウト

          cvs -d :pserver:anonymous@cvs.m17n.org:/cvs/root checkout riece

 3. configure の生成

          autoreconf -f -i -v

Debugging
=========

riece-debug を t に設定すると、デバッグ出力が有効になります。また、サーバからの生の出力が " *IRC*[<サーバ名>]" バッファに消されずに残ります。

Modules
=======

基本的に依存関係の上位にあるものから：

riece-globals
     大域変数の定義

riece-options
     ユーザオプションの定義

riece-version
     バージョンの定義

riece-inlines
     雑多なインライン関数の定義

riece-coding
     コーディングシステム関連の関数の定義

riece-complete
     ミニバッファでの補完を助ける関数の定義

riece-mode
     channel/user のモード管理

riece-identity
     channel/user object の大域表記を操作する関数の定義

riece-channel
     channel object 関連の定義

riece-user
     user object 関連の定義

riece-signal
     シグナル(see Signals)管理

riece-misc
     雑多な関数の定義(インライン関数を除く)

riece-display
     表示用バッファの管理

riece-server
     IRCサーバとの接続管理

riece-naming
     名前管理のための mediator のようなもの

riece-message
     message object 関連の定義

riece-filter
     プロセスフィルタのエントリポイント

riece-handle
     通常のメッセージのハンドラ。riece-filter から呼ばれる

riece-000
     000番台の numeric reply のハンドラ。riece-filter から呼ばれる

riece-200
     200番台の numeric reply のハンドラ。riece-filter から呼ばれる

riece-300
     300番台の numeric reply のハンドラ。riece-filter から呼ばれる

riece-400
     400番台の numeric reply のハンドラ。riece-filter から呼ばれる

riece-500
     500番台の numeric reply のハンドラ。riece-filter から呼ばれる

riece-commands
     コマンドの定義

riece
     エントリポイント。各バッファのモード定義など

Namespace management
====================

Riece は複数のサーバに同時に接続するため、サーバ毎に別々の名前空間を管理しています。この名前空間には、サーバのプロセスに結び付けられたバッファのローカル変数を介してアクセスします。

Obtaining server buffer
-----------------------

サーバのプロセスを得るには、まずはじめにサーバの名前を得る必要があります。サーバの名前は以下に挙げるいくつかの方法で取得できます。

 1. 大域変数 riece-overrinding-server-name の値

 2. riece-server-name がカレントバッファのローカル変数であるならば、既にプロセスのバッファにいるとみなせるので、riece-server-name の値そのもの

 3. riece-identity オブジェクトに結び付けられたサーバ名(後述)

こうして得たサーバ名で riece-server-process を呼出し、サーバのプロセスを取得します。

Identity
--------

複数のサーバに繋いだ場合、チャンネル名やニックを(サーバのバッファ上だけではなく)大域的に区別する必要が生じます。このような名前を表現するのが riece-identity オブジェクトです。

riece-identity オブジェクトは以下の 2 つの要素をもつベクターです。

prefix
     サーバローカルな名前

server
     サーバの名前

riece-identity オブジェクトに対する操作には以下のようなものがあります。

 -- Function: riece-make-identity prefix &optional server
     riece-identity オブジェクトを作成します。server が省略された場合には、 riece-find-server-name を使って取得したサーバ名を使います

 -- Function: riece-identity-prefix identity
     riece-identity オブジェクトからサーバローカルな名前を取り出します。

 -- Function: riece-identity-server identity
     riece-identity オブジェクトからサーバの名前を取り出します。

 -- Function: riece-identity-equal ident1 ident2
     2 つのriece-identity オブジェクトが同等か調べます。

 -- Function: riece-identity-equal-no-server ident1 ident2
     2 つのriece-identity オブジェクトのサーバローカルな名前が同等か調べます。

 -- Function: riece-identity-member elt list
     riece-identity オブジェクト ELT が LIST に含まれるか検査します。

Channel and user management
---------------------------

riece-identity オブジェクトによって識別される IRC のチャンネルとユーザはそれぞれ riece-channel オブジェクトと riee-user オブジェクトにより表現されます。

Channels
........

riece-channel は、IRC のチャンネルを表すオブジェクトです。以下の要素を持ちます。

users
     参加しているユーザの名前(局所名)のリスト

operators
     オペレータ権限をもつユーザの名前のリスト

speakers
     発言権をもつユーザの名前のリスト

modes
     チャンネルのモード(文字のリスト)

banned
     MODE +b で指定されたパターンの一覧

invited
     MODE +I で指定されたパターンの一覧

uninvited
     MODE +e で指定されたパターンの一覧

Users
.....

riece-user は、IRC に参加しているユーザを表すオブジェクトです。以下の要素を持ちます。

channels
     参加しているチャンネルの名前(局所名)のリスト

user-at-host
     "<user>@<host>" の形で与えられるユーザの情報

modes
     ユーザのモード(文字のリスト)

away
     AWAY 中かどうか

Mediator
........

チャンネルとユーザの参加・離脱を管理するために、 riece-naming という上位のモジュールを用意しています。これは、デザインパターンでいうところの Mediator パターンに相当するものです。

riece-naming を介することで、前述のチャンネル・ユーザオブジェクトに直接手を触れることなく、名前空間に安全にアクセスすることができます。

提供する主な関数は以下の 3 つです。

 -- Function: riece-naming-assert-join user-name channel-name
     ユーザがチャンネルに参加したことを表明します

 -- Function: riece-naming-assert-part user-name channel-name
     ユーザがチャンネルから離脱したことを表明します

 -- Function: riece-naming-assert-rename old-name new-name
     ユーザの名前が変更されたことを表明します

Signals
=======

画面の再描画を効率良く行うために、イベントと描画対象のオブジェクト(バッファや、モードラインの印 see Indicators)を結び付けるメカニズムを用意しています。

何らかのイベントが発生すると、シグナルが送出されます。シグナルの概念は、 Qt や GTK+ といった GUI ツールキットに用意されているものと同様です。

シグナルを送出するには、riece-emit-signal を使います。

 -- Function: riece-emit-signal signal-name &rest args
     SIGNAL-NAME で指示されるシグナルを、引数 ARGS とともに送出します

シグナルに応答するには、riece-connect-signal を使います。

 -- Function: riece-connect-signal signal-name slot-function &optional filter-function handback
     SIGNAL-NAME で指示されるシグナルに応答する関数 SLOT-FUNCTION を結び付けます。SLOT-FUNCTION に指定された関数は 2 つの引数を取ります。第1の引数ははシグナルを表します。また、第2の引数として、 HANDBACK 引数に与えられたオブジェクトがそのまま渡されます。

     FILTER-FUNCTION は、受信したシグナルに応答すべきかどうかを判定する関数です。この関数は引数としてシグナルオブジェクトを受け取り、nil または t を返すことが期待されます。返り値が nil の場合には、 SLOT-FUNCTION が呼ばれることはありません。

シグナルオブジェクトにアクセスするには、以下の関数を使います。

 -- Function: riece-signal-name
     シグナルの名前(シンボル)を返します。

 -- Function: riece-signal-args
     シグナル送出時に与えられた引数を返します。

現在、以下のシグナルが標準で登録されています：

channel-list-changed
     参加しているチャンネルの一覧の変化

user-list-changed
     チャンネルの参加者一覧の変化 (引数はチャンネルに相当する riece-identity オブジェクト)

channel-switched
     現在のチャンネルを移動

user-joined-channel
     ユーザがチャンネルに参加 (引数は、ユーザおよびチャンネルに相当する riece-identity オブジェクト)

user-left-channel
     ユーザがチャンネルから離脱 (引数は、ユーザおよびチャンネルに相当する riece-identity オブジェクト)

user-renamed
     ユーザが名前を変更 (引数は、以前と現在の名前に相当する riece-identity オブジェクト)

user-away-changed
     ユーザの離席状態の変化 (引数は、ユーザに相当する riece-identity オブジェクト)

user-operator-changed
     ユーザのオペレータ状態の変化 (引数は、ユーザに相当する riece-identity オブジェクト)

channel-topic-changed
     チャンネルのトピックの変化 (引数は、チャンネルに相当する riece-identity オブジェクト)

channel-modes-changed
     チャンネルのモードの変化 (引数は、チャンネルに相当する riece-identity オブジェクト)

channel-operators-changed
     チャンネルでオペレータ権限を持つユーザの一覧の変化 (引数は、チャンネルに相当する riece-identity オブジェクト)

channel-speakers-changed
     チャンネルで発言権を持つユーザの一覧の変化 (引数は、チャンネルに相当する riece-identity オブジェクト)

buffer-freeze-changed
     バッファの凍結状態の変化 (引数はバッファ)

Writing add-ons
===============

アドオンの条件を満たすモジュールは以下の関数を提供します。

<モジュール名>-requires
     依存する他のアドオン(シンボルのリスト)を返します(オプション)

<モジュール名>-insinuate
     初期化処理を行います

また、アドオンの説明を、変数 <モジュール名>-description に設定することもできます。この文字列は M-x riece-command-list-addons によるアドオンの一覧表示に使われます。

有効化・無効化に対応したアドオンは、変数 <モジュール名>-enabled に現在の状態を保持します。値が nil であれば無効、t であれば有効です。加えて、以下の関数を提供します。

<モジュール名>-enable
     アドオンを有効にします

<モジュール名>-disable
     アドオンを無効にします

Riece は起動時に以下の処理を行います。

 1. 変数 riece-addons に列挙されたモジュールを読み込む

 2. それぞれのモジュールに対し、<モジュール名>-requires が用意されていれば呼び出して依存グラフを作る

 3. 依存グラフに対してトポロジカルソート (cf. tsort(1)) を行う

 4. 得られた依存順序に従って <モジュール名>-insinuate 呼び出す

 5. もし、アドオンが有効化・無効化に対応しており、明示的に無効化されていなければ、 <モジュール名>-enableを呼び出す。

作成したアドオンは、load-path の通ったディレクトリ、または riece-addon-directory (デフォルトでは ~/.riece/addons/) に置くことで組み込み可能な状態になります。

Handler hooks
=============

Riece には、ハンドラフックと呼ばれる特殊なフックがあります。これらは IRC のメッセージを受け取った前後で実行されるフックです。

説明のために message を IRC のメッセージ名(PRIVMSG など)を全て小文字にしたものとします。

riece-<message>-hook
     message が届いたときに最初に呼ばれるフック

riece-after-<message>-hook
     message の処理が終わった後に呼ばれるフック

ここで riece-<message>-hook の返り値には意味があり、非 nil を返すものがあれば、その後の処理をおこないません。また、その場合には riece-after-<message>-hook も呼び出されません。

フックの引数は RFC2812 の prefix と Parameters に相当する 2 つの引数が渡ります。