Manual:Parser functions/ja

パーサ関数
Parser functions （1.7 以降で使用可能） は、テンプレートおよびその他のパーサ機能を、タグ機能拡張 よりもさらに密接に統合する方法を提供します. 1.6 には開発初期段階のパーサ関数が存在しますが、API と構文が異なるため、使用しないことを推奨します. 1.6.8 では、ParserFunctions 等の推奨モジュールは十分に動作するようです.

タグフック拡張機能 （この機能拡張は、通常、与えられた未処理テキストから HTML を返します） との比較では、タグフック機能拡張は他のパーサと統合することは事実上不可能です; 例えば、ある拡張機能の出力をテンプレートパラメータに使用することはできません. 拡張機能タグの内側でテンプレートを展開することは可能ですが、手作業で行う必要があります -- これはバージョン更新を経るに従い、間違いの起きやすい手順といえます.

パーサ関数の典型的な構文は以下の通りです:

パーサ関数の作成は、タグフックを作成する場合よりも多少込み入っています. これは、関数名がマジックワードでなければならないためです; マジックワードは、別名および多言語対応をサポートする一種のキーワードです.

パーサ関数機能拡張の例
パーサ関数を生成する拡張機能の一例を以下に示します.

この機能拡張が有効化されると、以下の記述は

*

以下の出力を生成します:


 * param1 is hello and param2 is hi

より複雑な関数
より複雑な関数を記述する場合には、フック関数を _body.php または .hooks.php ファイルに分離し、これらを適当なクラスの静的関数としてもよいでしょう. この場合、クラスは $wgAutoloadClasses でロードして、フックから静的関数を呼び出すことができます. 例えば:

以下のコードを新しく  ファイルに挿入します:

次に、以下のコードを新しく  ファイルに挿入します:

キャッシュ
タグ機能拡張の場合と同様に、動的機能拡張としたい場合は、$parser->disableCache を使用してキャッシュを無効にできます

出力の構文解析を制御する
作成したパーサ関数が返す Wikitext が完全に構文解析されるようにするには、戻り値の noparse オプションに false をセットします:

noparse の既定値は、バージョン 1.12 付近のどこかで、少なくともある状況下において、false から true に変更されたようです.

これを裏返すと、作成したパーサ関数が、Wikitext ではなく、構文解析されない HTML を返すようにするには、以下のように指定します:

ところが、 This is a test. の記述は、以下のような出力を生成します:

This is

param1 is hello and param2 is hi a test.

これは、パーサ関数の HTML 出力に、ハードコードされた "\n\n" 文字列が前置されることが原因です. この現象を回避するために、HTML コードが周りのテキストに対してインラインとしてレンダリングされるようにするには、以下のように記述します:

命名規則
既定では、MW によりハッシュ記号 （ナンバ記号、"#"） が各パーサ関数の名前に付加されます. この付加を抑制する （パーサ関数の名前に "#" 接頭子がつかないままにする） には、以下 で説明する setFunctionHook に渡すオプションのフラグ引数に SFH_NO_HASH 定数を含めます.

ハッシュ接頭子を付加しないことを選択した場合は、ページタイトルがコロン + 当該関数名で始まるページをトランスクルードすることができなくなる点に注意してください. 特に、関数名が名前空間名と一致しないようにしてください. インターウィキトランスクルージョン が有効な場合は、関数名がインターウィキ接頭辞とも一致しないようにしてください.

setFunctionHook フック
パーサインターフェイスについてのより詳細な情報に関しては、includes/Parser.php の setFunctionHook に関する記述を参照してください. 左記埋め込みコメント （の、おそらく最新版ではないもの） を、以下に転記します:

function setFunctionHook( $id, $callback, $flags = 0 )

パラメータ:


 * string $id - マジックワード ID
 * mixed $callback - 使用するコールバック関数 （およびとオブジェクト）
 * integer $flags - オプション項目、SFH_NO_HASH 定数を設定して "#" 無しで関数を呼び出します.

戻り値: 同名の旧コールバック関数 （もしあれば）

例えば  のような関数を作成する場合、このコールバック関数は以下の形式になります:

このコールバックは、関数の結果テキストか、またはテキスト （要素 0）およびいくつかのフラグ （残りの要素）からなる配列のどちらかを返します. フラグ名はキーで指定します. 有効なフラグは以下の通りです:


 * found : 返されるテキストは有効で、テンプレートの処理を停止します. 既定値は on です.
 * nowiki : 戻り値の Wiki マークアップがエスケープされます.
 * noparse : 安全ではない HTML タグがストリップされていない、等.
 * noargs : 戻り値内の三重波括弧引数を置換しません.
 * isHTML : 返されるテキストは HTML で、Wikitext 変形に対して保護します.

関連情報

 * Manual:Extensions
 * Manual:Tag extensions
 * Manual:Magic words
 * Manual:Parser.php
 * Extensions FAQ
 * Help:Extension:ParserFunctions
 * ParserFunctions extension は、有名なパーサ関数のコレクションです.