Manual:Parser functions/ja

タグの拡張機能

パーサー関数

フック

特別ページ

スキン

マジックワード

パーサ関数

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

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

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

{{ #functionname: param1 | param2 | param3 }}

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

パーサ関数機能拡張の例

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

<?php
$wgExtensionCredits['parserhook'][] = array(
        'path' => __FILE__,     // SVN リビジョン番号を表示するためのマジックナンバー
        'name' => "Example Extension",
        'description' => "A simple example parser function extension",
                                // i18n がサポートされる場合は descriptionmsg を使用すべきです
                                // （でもこれは簡単な例なので）。
        'version' => 1, 
        'author' => "Me",
        'url' => "http://www.mediawiki.org/w/index.php?title=Manual:Parser_functions",
);
 
# 関数の設定を定義します
$wgHooks['ParserFirstCallInit'][] = 'efExampleParserFunction_Setup';
# マジックワードを初期化するためのフックを追加します
$wgHooks['LanguageGetMagic'][]       = 'efExampleParserFunction_Magic';
 
function efExampleParserFunction_Setup( &$parser ) {
        # マジックワード "example" を新しい関数に関連付けする関数フックをセットします
        $parser->setFunctionHook( 'example', 'efExampleParserFunction_Render' );
        return true;
}
 
function efExampleParserFunction_Magic( &$magicWords, $langCode ) {
        # マジックワードを追加します
        # 1 番目の配列要素で、大小文字識別の有無を指定します。 今回の例（0）は識別あり、1 で識別なし
        # 残りの全ての要素で、作成するパーサ関数に対する別名を指定します。
        $magicWords['example'] = array( 0, 'example' );
        # true を返さない場合には、他のパーサ関数機能拡張はロードされません。
        return true;
}
 
function efExampleParserFunction_Render( $parser, $param1 = '', $param2 = '' ) {
        # パーサ関数本体です
        # 入力パラメータはテンプレートで展開される Wikitext です
        # 出力も同様に Wikitext になります
        $output = "param1 is $param1 and param2 is $param2";
        return $output;
}

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

* {{#example:hello | hi }}

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

• param1 is hello and param2 is hi

より複雑な関数

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

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

$wgAutoloadClasses['MyExtensionHooks'] = "$dir/MyExtension.hooks.php";
$wgHooks[' ... '][] = 'MyExtensionHooks::MyExtensionFunction';

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

class MyExtensionHooks {
      public static function MyExtensionFunction( ... ) { ... }
}

キャッシュ

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

パーサインターフェイス

出力の構文解析を制御する

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

return array( $output, 'noparse' => false );

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

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

return array( $output, 'noparse' => true, 'isHTML' => true );

ところが、

This is {{#example:hello | hi }} a test.

の記述は、以下のような出力を生成します:

This is

param1 is hello and param2 is hi a test.

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

return $parser->insertStripItem( $output, $parser->mStripState );

命名規則

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

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

setFunctionHook フック

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

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

パラメータ:

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

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

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

function myParserFunction( &$parser, $arg1, $arg2, $arg3 ) { ... }

このコールバックは、関数の結果テキストか、またはテキスト （要素 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 は、有名なパーサ関数のコレクションです。