Plugin

ここではプラグイン (Plugin Syntax) の開発について解説します。

• ディレクトリとファイル
• Plugin Syntax
  • 大文字小文字は考慮してはならない
  • パラメータの指定
• プラグインの実装方法
• Convert type Plugin
• Action type Plugin
• Other tips
  • Plugin Syntax 内の [[ と ]]
  • 高速な変換のために

ディレクトリとファイル

プラグインディレクトリの名前は plugins を推奨しています。 また、プラグインディレクトリは、KARAS の実行ファイルと同じ階層に置くことを推奨しています。 ただし、あなたのシステムが持つ既存の設定がこれらのルールと衝突する場合には、変更しても良いです。 標準のコンバータでは、ディレクトリ名とそのパスを変更するためには、ソースコードを直接修正する必要があります。

プラグインのファイル名は、そのプラグインの、class あるいは module などの名前と、等しい必要があります。 ファイル名が大文字であるか小文字であるかは考慮されます。 例えば、名前が Sample というプラグインは、 Sample.ext というファイル名である必要があります。 このとき、 class あるいは module の名前は、Sample となります。 あなたのシステムがこの命名規則によって問題を持つときは、この規則を変更することができます。 標準のコンバータでは、命名規則を変更するためには、ソースコードを直接修正する必要があります。

Plugin Syntax

KARAS では、Plugin の構文は、次のように定められています。

[[ PluginName :: option1 :: option2... ::: markedupText]]

[[[ PluginName :: option1 :: option2... ::: markedupText]]]

大文字小文字は考慮してはならない

PluginName は大文字と小文字を無視します。 大文字の場合も小文字の場合も、同じプラグインが呼び出されるようにしてください。

プラグインの処理を変更するために option1 - optionX に与える文字列は、 大文字か小文字かを考慮してはいけません。例えば、true / false を指定するとき、 TRUE / FALSE でも同じ結果が得られなければいけません。

パラメータの指定

オプションは必ず :: で区切ります。 , などを使って区切ることは禁止されています。 パラメータではない、KARAS によってマークアップされたテキストを指定する場合は、 オプションの最後に ::: によって1度だけ追加できます。

プラグインの実装方法

標準のコンバータでは、プラグインの構文は、KARAS の他の構文が変換されるよりも前に変換されます。 KARAS 以外の構文が、プラグインの中で書かれることがあるためです。例えば LaTeX はその1つです。 ふつう、システムはこのような実装になると思います。しかし、もしも必要なら、変換する順序を変更しても良いです。 プラグインを実装するとき、その実装方法は制限されません。プラグイン構文のフォーマットだけを守る必要があります。

Convert type Plugin

Convert type plugin は、あるマークアップされたテキストから新しいテキストを出力するためのプラグインです。

[[PluginName :: options0 :: options1 :: ･･･ :: markedupText]]

public static Convert(options, markedupText)
return string

引数 markedupText は、プラグイン構文でマークアップされた文字列型のテキストです。 引数 options は、プラグイン構文で、オプションとしてマークアップされた文字列型の配列です。 したがって、例えば、値型などのオプションを指定するときは、プラグイン内で値型に変換する必要があります。 戻り値は、マークアップされたテキストを置き換える新しいテキストです。

Action type Plugin

Action type plugin は、テキスト全体を使って新しいテキストを出力するためのプラグインです。 例えば、テキストに含まれる見出しをすべて探して、一覧にするようなプラグインを作ることができます。

[[[PluginName::options0 :: options1 :: ･･･ :: markedupText]]]

public static string Action(text, options)
return string

引数 text は、Action type plugin が書かれたテキストのすべての文字列です。 引数 options は、Plugin Syntax でマークアップされた文字列型の配列です。 したがって、例えば、値型などのオプションを指定するときは、プラグイン内で値型に変換する必要があります。 戻り値は、マークアップされたテキストを置き換える新しいテキストです。

Other tips

Plugin Syntax 内の [[ と ]]

プラグイン構文の中に、プラグイン構文ではない [[ や ]] 記号を書くことはできません。 これは、解決不可能な問題です。この問題を回避するためには、それらの記号を \ を用いてエスケープすることができます。 あるいは、そのプラグインに実装する処理によって、回避します。

高速な変換のために

高速な変換が必要なとき、プラグインはあらかじめコンパイルされていることが重要です。 例えば Wiki のようなシステムでプラグインを利用するとき、システムの起動時にコンパイルするのは良い方法です。 あるいは、変換した HTML をキャッシュすることが考えられます。

C# や Java などの言語は、実行時のコンパイルがとても遅いです。 そのような状況では、コンパイル済みのプラグインを利用するかもしれません。 ただし、それを利用するときは注意が必要です。コンパイル済みのプラグインはソースコードが読めません。 したがって、あなた以外のユーザが開発したコンパイル済みのプラグインを利用するとき、それは悪質なコードを出力するかもしれません。

この問題を解決するには、プラグインのソースコードを公開し、ユーザによってコンパイルされる必要があります。 開発者は、公開方法について注意する必要があります。