Manual:Parser functions/ja

MediaWiki 1.7で追加されたパーサー関数は、パーサーと密接に連動する拡張機能の一種です. 「パーサー関数」という言葉を、単純なパーサー関数の集まりである と混同しないようにしてください. （これについては を参照してください. ）

説明
タグ拡張機能は未処理のテキストを取り込んでブラウザに HTML を返すのに対して、パーサー関数はページ上のその他の要素と「相互作用」ができます. たとえばパーサ関数の出力はテンプレート変数として利用したりリンクの作成に使うことができます.

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

詳細について、の説明はを参照してください. その説明文書は次の内容を扱います.


 * コールバック関数の構文は次のとおりです.
 * あるいは :
 * あるいは :

The first variant of the call passes all arguments as plain text. The second passes all arguments as an array of s, except for the first, which is currently text, though this may change in the future. These represent the unexpanded wikitext. The  parameter can be used to expand these arguments as needed. This is commonly used for conditional processing so that only the "true" case is evaluated with an if- or switch-like parser function. The frame object can also climb up the document tree to get information about the caller and has functions to determine and manage call depth, time-to-live, and whether the result of the parser function is volatile.

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



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

登録は extension.json に、コードは src/ExampleExtensionHooks.php にそれぞれ入ります:

拡張機能ディレクトリ（src/ サブディレクトリではない）にある別のファイル ExampleExtension.i18n.php には以下の内容を含めておく必要があります.

この拡張機能を有効にすると、



出力結果:


 * param1 is hello and param2 is hi and param3 is hey

Within LocalSettings.php
Magic words and their handling parser functions can be defined entirely in LocalSettings.php.



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

以下のコードを  ファイルに追加します:
 * その他の様式はイベントハンドラの記述を参照してください.

次に、以下のコードを  ファイルに追加します:

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

これはパフォーマンスに大きな悪影響を与えるため、必要な場合にのみ使用してください.



パーサー インターフェイス


出力の構文解析の制御
作成したパーサー関数が返すウィキテキストが完全に構文解析されるようにする (テンプレートの展開を含む) には、戻り値の  オプションに false を設定します:

の既定値は、ある時点、バージョン 1.12 付近のどこかで、false から true に変更されたようです.

逆に、作成したパーサー関数が、ウィキテキストを返すのではなく、構文解析されないままの HTML を返すようにするには、以下のように指定します:

命名
MW は既定でそれぞれのパーサー関数名の先頭にハッシュ記号 (「#」) を追加します. 追加させない (パーサー関数名に接頭辞「#」を付けない) ためには、以下で説明しているように、SFH_NO_HASH定数をオプションのflags引数のsetFunctionHookに挿入します.

もしハッシュ記号を接頭辞に使わない名称を選ぶ場合は、その関数名の後ろにコロンを付けて作ったページ名を参照呼出しできないことにご留意ください. 特に、関数名は名前空間名と同名にしてはいけません. ウィキ間参照読み込みのを有効にした場合には、関数名をウィキ間接頭辞と同名にしてはいけません.



setFunctionHook フック
パーサーに関連するインターフェースの詳細は、includes/Parser.phpに同梱した説明文書 setFunctionHook を参照してください. 以下はこれらのコメントを転写したものです (古い可能性あり).

function setFunctionHook( $id, $callback, $flags = 0 ) パラメーター:


 * string $id - マジックワード ID
 * mixed $callback - 使用するコールバック関数 (とオブジェクト)
 * integer $flags - (省略可能) 関数を「#」なしで呼び出すようにするには、SFH_NO_HASH 定数を設定します.

戻り値: この名前の元のコールバック関数 (ある場合)

たとえば など関数の作成. コールバック関数の構文の書き方を示します.

コールバックの戻り値は関数が出力した文字列もしくはまたはテキストを含む配列要素0と、他の要素のフラグいくつかを示します. フラグの名前はキーで指定します. 有効なフラグは以下のとおりです.


 * forceRawInterwiki
 * Force interwiki transclusion to be done in raw mode, not rendered.


 * found
 * 戻り値のテキストは有効で、テンプレートの処理を停止. これは既定で有効です.


 * isChildObj
 * The text is a DOM node needing expansion in a child frame.


 * isHTML
 * 戻り値の文字列は HTMLで、ウィキテキスト変換から保護する必要がある But see discussion


 * isLocalObj
 * The text is a DOM node needing expansion in the current frame.


 * noparse
 * 暗線ではない HTML タグは除去しないetc.


 * nowiki
 * 戻り値に対するウィキマークアップは回避されるべき


 * preprocessFlags
 * Use these flags when parsing the returned text. This only applies when noparse is.


 * text
 * The text returned from the function. If isChildObj or isLocalObj are specified, this should be a DOM node instead.


 * title
 * The Title object where the text came from.

Expensive parser functions
Some parser functions represent a significant use of a wiki's resources and should be marked as "expensive". The number of expensive parser functions on any given page is limited by the setting. What counts as expensive is left up to the function itself, but typically, anything that is likely to cause a delay that extends beyond simple processing of data should be considered. This includes things like database reads and writes, launching a shell script synchronously, or file manipulation. On the other hand, not all such functions should necessarily be tagged. Semantic MediaWiki, for example, only marks a percentage of its database reads as expensive. This is due to the fact that on certain data-intensive pages, it could easily overflow the normal expensive parser function limits. In cases like this, the potential for noticeably slower performance that doesn't get flagged as expensive is a trade-off to having the functionality that SMW offers.

To mark your parser function as expensive, from within the body of the function's code, use. The return value will be if the expensive function limit has been reached or exceeded.



名前付きパラメーター
パーサー関数はテンプレートもしくはタグ拡張機能と異なり、名前付きパラメーターをサポートしないものの、ときにはそれを回避する役に立ちます. 利用者は引数を分けるために縦棒 ( | ) を使い慣れているため、パーサー関数のコンテキストでも同様の記述ができると便利です. これを実現する方法の簡単な例を示します.



関連項目

 * ParserFunctions 拡張機能は、よく知られたパーサー関数のコレクションです.
 * - an (incomplete) list of parser functions provided by core and extensions
 * パーサー フック PHP ライブラリ - 宣言型パーサーフックのためのオブジェクト指向インターフェイスを提供する
 * ParserFunctions 拡張機能は、よく知られたパーサー関数のコレクションです.
 * - an (incomplete) list of parser functions provided by core and extensions
 * パーサー フック PHP ライブラリ - 宣言型パーサーフックのためのオブジェクト指向インターフェイスを提供する
 * ParserFunctions 拡張機能は、よく知られたパーサー関数のコレクションです.
 * - an (incomplete) list of parser functions provided by core and extensions
 * パーサー フック PHP ライブラリ - 宣言型パーサーフックのためのオブジェクト指向インターフェイスを提供する
 * パーサー フック PHP ライブラリ - 宣言型パーサーフックのためのオブジェクト指向インターフェイスを提供する