.. _plugin_specification:

プラグインの仕様について
##################################################
.. note::
    プラグインを作ってくれる方を募集しています！
    まだまだ、どんなプラグインが必要とされ、どんなインターフェイスが必要なのかを、一人では洗い出せていません。
    APIの仕様も、十分ではありませんし、皆さんのご意見をいただきたいです。


スクリプトの動作環境
**************************************************
プラグイン機能は、Java言語標準のスクリプトエンジンを利用して、ChatLoggerPlus内でスクリプトを動作させるように作っています。
このため、JVMで動作するスクリプト言語が一通り使えます。

環境を準備さえすれば、PythonやRuby、Groovyといった言語が使えるようになっているハズです。
ですが、ほとんどのユーザーは環境準備をしていないと思われるので、プラグインを配布する場合は、標準で使えるJavaScriptで作成することになります。

.. note::
    このため、JavaScript以外は動作未確認です。
    ChatLoggerPlusは、プラグインの拡張子で言語を判断して動くように作っています。
    もし、他の言語で動作を確認された方がおられましたら、是非ご連絡ください。

JavaScriptの作成にはRhinoの情報が役に立ちます。
(正式にはJSR223で定義されているものでRhinoは若干異なるようです。JavaImporterが使えない等)

手元の環境では、「Mozilla Rhino 1.6 release 2, ECMAScript 1.6」と表示されていますので、参考にしてください。

以下のサイトが参考になりましたので、リンクを張っておきます。

 * `Java スクリプトプログラマーズガイド <http://docs.oracle.com/javase/jp/6/technotes/guides/scripting/programmer_guide/index.html>`_ 
 * `5. スクリプティング機能 | TECHSCORE(テックスコア) <http://www.techscore.com/tech/Java/JavaSE/JavaSE6/5/>`_ 
 * `Java SE 6 じゃじゃ馬ならし Scripting <http://www.javainthebox.net/laboratory/JavaSE6/scripting/scripting.html>`_ 

JavaScriptそのものの記述については、検索すると沢山サイトが見つかると思います。
うまく活用してください。

.. note::
    スクリプトは、主にJavaScript言語で作ることができ、テキストエディタがあれば開発可能です。特別な開発環境は必要ありません。
    是非、チャレンジしてみてください！


パーミッション（権限）について
**************************************************
パーミッション（権限）には、以下のような種類が存在しています。

.. csv-table:: パーミッション（権限）一覧
    :header: "制限対象", "パーミッション取得メソッド", "表示名", "詳細"
    :widths: 20, 20, 10, 50

     :java:ref:`setMessage` ,  :java:ref:`registerPermissionMessageModification` , "Modify", "チャットメッセージを加工するパーミッションを要求します。"
     :java:ref:`addAfterMessage` ,  :java:ref:`registerPermissionAddAfterMessage` , "Add", "チャットメッセージを追加するパーミッションを要求します。"
     :java:ref:`writeStack` ,  :java:ref:`registerPermissionWriteStack` , "WS/xxxx", "スタックに書き込むパーミッションを要求します。（実質新規作成の意味合いです）"
     :java:ref:`readStack` ,  :java:ref:`registerPermissionReadStack` , "RS/xxxx", "スタックを読み込むパーミッションを要求します。（実質、既に存在するスタックなら読み書きできます）"

この表の制限対象に書かれたメソッドを使用するためには、 :java:ref:`onInitialize` で、パーミッション取得メソッドを呼び出さなければなりません。

詳しくはAPIリファレンスの :java:ref:`PluginSettings` も参照してください。


スタックについて
**************************************************
スタックは以下のような特徴があります。

 * スタックには、問い合わせ用の「キー文字列」に紐付けして、値を保持することができます。
 * スタックは、１つの発言の処理中に値を保持する物です。保持した情報は、次の発言には引き継がれません。
 * スタックに対して、情報の読み書きを行い、プラグイン同士の値の受け渡しができるようにしています。
 * スタックには、クラスオブジェクトも受け渡すことが出来ます。（これを使えば、一つのスタックで複数の値が渡せます）
 * スタックを使い連携するプラグインは、プラグインの実行順序が重要になります。
 * スタックに書き込む同一キーのプラグインは１つでなければなりませんが、スタックを読み込む同一キーのプラグインは複数でも動作可能です。（ただしスタックにある情報の状態はうまく管理しなければなりません）
 * プラグインは単機能で役割分担することができ、ユーザーはプラグインの組合せで、目的の処理を行えるようになります。
 * プラグインの並び替えで、RS権限のプラグインの前に、同一キーのWS権限のプラグインが無い場合はエラーになります。このため、RS権限の前にWS権限が存在することが保証されます。

.. tip::
    スタックは、プラグイン１つにつき、キー文字列を複数登録が可能です。
    （ただし、多すぎるのは問題です。ユーザーが認知する必要のあるものだけに限定しましょう。通常は１個あれば十分です。多くても２～３個で済ませましょう）

スタックを使ったプラグイン連携について
==================================================
それでは、ここでは「概念」を理解してもらうため、具体的なスクリプトのコードなしで使用例を挙げます。
実際のスクリプトのコード例については、 :ref:`tutorial_create_plugin` をご覧ください。

例題の前提条件
--------------------------------------------------
次のようなプラグインＡとＢが存在し、既にプラグインの処理順がＡ→Ｂとなっているとします。
また、スタックのキー文字列として、ここでは「Flag」という名前を使うことにします。
（キー文字列は、連携しない他のプラグインとかぶらなければ、なんでもよいです）

 #. プラグインＡ：チャット文字をチェックし、ある条件を満たしたメッセージの場合は、スタックにフラグを立てるプラグイン
 #. プラグインＢ：スタックのフラグをチェックし、そのフラグを元にチャットメッセージを加工するプラグイン

このような仕様のプラグインを作る場合、それぞれのプラグインは、以下のような実装が必要です。

プラグインＡの実装
--------------------------------------------------
チャット文字をチェックし、ある条件を満たしたメッセージの場合は、スタックにフラグを立てるプラグイン

 * プラグイン初期化処理にて、registerPermissionWriteStackを使い、スタックのキー文字列「Flag」を登録する。
 * チャットメッセージの処理にて、文字列がある条件を満たすかチェックし、満たす場合は、writeStackを使って、スタック「Flag」にフラグを立てる。

プラグインＢの実装
--------------------------------------------------
スタックのフラグをチェックし、そのフラグを元にチャットメッセージを加工するプラグイン

 * プラグイン初期化処理にて、registerPermissionReadStackを使い、スタックのキー文字列「Flag」を登録する。
 * プラグイン初期化処理にて、registerPermissionMessageModificationを使い、チャット加工をすることを登録する。
 * チャットメッセージの処理にて、readStackを使って、スタック「Flag」にフラグが立っているかチェックし、フラグが立っている場合は、setMessageを使ってチャット文字を加工する。

スタック連携の使いどころ
--------------------------------------------------
これを全てここで列挙することは出来ませんが、思いつく例をいくつか挙げておきます。

    スクリプトの編集なしで、ユーザーに機能を選択させたい場合
        たとえば、上記の例のように、判断部分と処理部分を分けておけば、処理部分のプラグインを複数用意しておくことで、ユーザーにより好みの処理を選んでもらうことができます。
        上記例でいえば、プラグインＢは文字を赤色にする機能とし、プラグインＣは緑色にする、といった使い方です。
        また、逆に判断部分を複数用意するパターンも考えられます。

    重い処理を複数のプラグインで共有したい場合
        たとえば、サンプルプラグインの「MiNeRa bot」では、１つのプラグインの中で大きく分けて二つのことを行っています。
        一つは「TinySegmenterによる日本語の分かち書き」です。もう一つは「分かち書きの結果を使った、マルコフ連鎖による文字列生成」です。
        分かち書きの結果を別の用途でも使いたい場合、このプラグインは、二つの機能を分割して別々のプラグインにすることも考えられます。
        こうすれば、１つの発言に対する分かち書きの処理は１回だけにし、分かち書きの結果を使うプラグインを２つ、３つ同時に使うことも可能です。

    特殊な機能を提供するプラグインを公開する場合
        たとえば、「音を鳴らすプラグイン」といった特殊なプラグインを公開し、スタックの使い方だけ提示します。
        別のプラグインの作り手がこれを使えば、音を鳴らす部分を作る必要はなくなります。
        このようにスクリプトのパーツとしての使い方も考えられます。