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 によりハッシュ記号 （ナンバ記号、"#"） が各パーサ関数の名前に付加されます. この付加を抑制する （パーサ関数の名前に "#" 接頭子がつかないままにする） には、[#The setFunctionHook hook|以下]] で説明する 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の変形に対して保護します

パーサ関数拡張機能はパーサ関数のよく知られたコレクションです.