Manual:パーサー関数かんすう

MediaWiki 1.7で追加ついかされたパーサー関数かんすうは、パーサーと密接みっせつに連動れんどうする拡張かくちょう機能きのうの一いち種しゅです。 「パーサー関数かんすう」という言葉ことばを、単純たんじゅんなパーサー関数かんすうの集あつまりである Extension:ParserFunctions と混同こんどうしないようにしてください。 （これについては Help:Extension:ParserFunctions を参照さんしょうしてください。）

説明せつめい

タグ拡張かくちょう機能きのうは未み処理しょりのテキストを取とり込こんでブラウザに HTML を返かえすのに対たいして、パーサー関数かんすうはページ上じょうのその他たの要素ようそと「相互そうご作用さよう」ができます。たとえばパーサ関数かんすうの出力しゅつりょくはテンプレート変数へんすうとして利用りようしたりリンクの作成さくせいに使つかうことができます。

パーサー関数かんすうの典型てんけい的てきな構文こうぶんは以下いかの通とおりです:

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

詳細しょうさいについて、Parser::setFunctionHook ( $id, $callback, $flags = 0 )の説明せつめいはthe documentationを参照さんしょうしてください。その説明せつめい文書ぶんしょは次つぎの内容ないようを扱あつかいます。

コールバック関数かんすうの構文こうぶんは次つぎのとおりです。

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

あるいは SFH_OBJECT_ARGS:

function myParserFunction( $parser, $frame, $args ) { ... }

The first variant of the call passes all arguments as plain text. The second passes all arguments as an array of PPNode s, except for the first ($args[0]), which is currently text, though this may change in the future. These represent the unexpanded wikitext. The $frame 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 にそれぞれ入はいります:

{
	"name": "ExampleExtension",
	"author": "Me",
	"version": "1.0.0",
	"url": "https://www.mediawiki.org/wiki/Extension:ExampleExtension",
	"descriptionmsg": "exampleextension-desc",
	"license-name": "GPL-2.0-or-later",
	"type": "parserhook",
	"MessagesDirs": {
		"ExampleExtension": [
			"i18n"
		]
	},
	"AutoloadClasses": {
		"ExampleExtensionHooks": "src/ExampleExtensionHooks.php"
	},
	"ExtensionMessagesFiles": {
		"ExampleExtensionMagic": "ExampleExtension.i18n.php"
	},
	"Hooks": {
		"ParserFirstCallInit": "ExampleExtensionHooks::onParserFirstCallInit"
	},
	"manifest_version": 1
}

<?php
class ExampleExtensionHooks {
   // レンダリング コールバックをパーサーに登録とうろくします
   public static function onParserFirstCallInit( Parser $parser ) {

      // 関数かんすうフックを作成さくせいし、"example" マジックワードとrenderExample()を対応たいおうさせます
      $parser->setFunctionHook( 'example', [ self::class, 'renderExample' ] );
   }

   // {{#example:}}の出力しゅつりょくを表示ひょうじ。
   public static function renderExample( Parser $parser, $param1 = '', $param2 = '', $param3 = '' ) {

      // 入力にゅうりょくパラメーターがウィキテキストでテンプレートを展開てんかいします。
      // 出力しゅつりょくもウィキテキストになります。
      $output = "param1 is $param1 and param2 is $param2 and param3 is $param3";

      return $output;
   }
}

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

<?php
/**
 * @license GPL-2.0-or-later
 * @author Your Name (YourUserName)
 */

$magicWords = [];

/** English
 * @author Your Name (YourUserName)
 */
$magicWords['en'] = [
   'example' => [ 0, 'example' ],
];

この拡張かくちょう機能きのうを有効ゆうこうにすると、

• {{#example: hello | hi | hey}}

出力しゅつりょく結果けっか:

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

magicWords引数ひきすうは必須ひっすでありオプションではありません。省略しょうりゃくするとパーサー関数かんすうはまったく機能きのうしません。{{#example: hello | hi}} は拡張かくちょう機能きのうがインストールされていない状態じょうたいとして表示ひょうじされます。 If only the language-specific array is initialized and not the magicWords array itself, this can cause localization errors as translations from other extensions leak into yours. マジックワードの関連かんれん付づけは、国際こくさい化かファイルではなく、PHP のインラインで行おこなうことができます。 これは、LocalSettings.php でフックを定義ていぎする際さいに便利べんりです

MediaWiki\MediaWikiServices::getInstance()->getContentLanguage()->mMagicExtensions['wikicodeToHtml'] = ['MAG_CUSTOM', 'custom'];

Within LocalSettings.php

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

$wgHooks['ParserFirstCallInit'][] = function ( Parser $parser ) 
{
	MediaWiki\MediaWikiServices::getInstance()->getContentLanguage()->mMagicExtensions['wikicodeToHtml'] = ['wikicodeToHtml', 'wikicodeToHtml'];

	$parser->setFunctionHook( 'wikicodeToHtml', 'wikicodeToHtml' );
};
 
function wikicodeToHtml( Parser $parser, $code = '' ) 
{
	$title = $parser->getTitle();
	$options = $parser->Options();
	$options->enableLimitReport(false);
	$parser = $parser->getFreshParser();
	return [$parser->parse($code, $title, $options)->getText(), 'isHTML' => true];
}

より長ながい関数かんすう

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

以下いかのコードを extension.json ファイルに追加ついかします:

"Hooks": {
	"ParserFirstCallInit": "ExampleExtensionHooks::onParserFirstCallInit"
},
"AutoloadClasses": {
	"ExampleExtensionHooks": "src/ExampleExtensionHooks.php"
}

• その他たの様式ようしきはイベントハンドラの記述きじゅつを参照さんしょうしてください。

次つぎに、以下いかのコードを src/ExampleExtensionHooks.php ファイルに追加ついかします:

class ExampleExtensionHooks {
      public static function onParserFirstCallInit( Parser $parser ) {
           $parser->setFunctionHook( 'example', [ self::class, 'renderExample' ] );
      }
}

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

出力しゅつりょくの構文こうぶん解析かいせきの制御せいぎょ

作成さくせいしたパーサー関数かんすうが返かえすウィキテキストが完全かんぜんに構文こうぶん解析かいせきされるようにする (テンプレートの展開てんかいを含ふくむ) には、戻もどり値ちの noparse オプションに false を設定せっていします:

return [ $output, 'noparse' => false ];

noparse の既定きてい値ちは、ある時点じてん、バージョン 1.12 付近ふきんのどこかで、false から true に変更へんこうされたようです。

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

return [ $output, 'noparse' => true, 'isHTML' => true ];

命名めいめい

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

もしハッシュ記号きごうを接頭せっとう辞じに使つかわない名称めいしょうを選えらぶ場合ばあいは、その関数かんすう名めいの後うしろにコロンを付つけて作つくったページ名めいを参照さんしょう呼出よびだししできないことにご留意りゅういください。特とくに、関数かんすう名めいは名前なまえ空間くうかん名めいと同名どうめいにしてはいけません。ウィキ間あいだ参照さんしょう読よみ込こみの[1]を有効ゆうこうにした場合ばあいには、関数かんすう名めいをウィキ間あいだ接頭せっとう辞じと同名どうめいにしてはいけません。

setFunctionHook フック

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

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

パラメーター:

• string $id - マジックワード ID
• mixed $callback - 使用しようするコールバック関数かんすう (とオブジェクト)

• integer $flags - (省略しょうりゃく可能かのう) 関数かんすうを「#」なしで呼よび出だすようにするには、SFH_NO_HASH 定数ていすうを設定せっていします。

Set it to SFH_OBJECT_ARGS (2) to pass a PPFrame object and array of arguments instead of a series of function arguments, for which see above. Defaults to 0 (no flags).

戻もどり値ち: この名前なまえの元もとのコールバック関数かんすう (ある場合ばあい)

たとえば{{#sum:1|2|3}}など関数かんすうの作成さくせい。コールバック関数かんすうの構文こうぶんの書かき方かたを示しめします。

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

コールバックの戻もどり値ちは関数かんすうが出力しゅつりょくした文字もじ列れつもしくはまたはテキストを含ふくむ配列はいれつ要素ようそ0と、他たの要素ようそのフラグいくつかを示しめします。フラグの名前なまえはキーで指定していします。 有効ゆうこうなフラグは以下いかのとおりです。

Name	Type	Default	Description
found	Boolean	true	戻もどり値ちのテキストは有効ゆうこうで、テンプレートの処理しょりを停止ていし。これは既定きていで有効ゆうこうです。
text	?	?	The text to return from the function. If isChildObj or isLocalObj are specified, this should be a DOM node instead.
noparse	Boolean	true	true if text should not be preprocessed to a DOM tree, e.g. unsafe HTML tags should not be stripped, etc.
isHTML	Boolean	?	戻もどり値ちの文字もじ列れつは HTMLで、ウィキテキスト変換へんかんから保護ほごする必要ひつようがある But see discussion
nowiki	Boolean	usually false	true if wiki markup in the return value (text) should be escaped.
isChildObj	Boolean	?	true if the text is a DOM node needing expansion in a child frame.
isLocalObj	Boolean	?	true if he text is a DOM node needing expansion in the current frame. The default value depends on other values and outcomes.
preprocessFlags	?	false	Optional PPFrame flags to use when parsing the returned text. This only applies when noparse is false.
title	?	false	The Title object where the text came from.
forceRawInterwiki	Boolean	?	true if interwiki transclusion must be forced to be done in raw mode and not rendered.

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 $wgExpensiveParserFunctionLimit 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 $result = $parser->incrementExpensiveFunctionCount();. The return value will be false if the expensive function limit has been reached or exceeded.

名前なまえ付つきパラメーター

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

function ExampleExtensionRenderParserFunction( &$parser ) {
	// Suppose the user invoked the parser function like so:
	// {{#myparserfunction: foo=bar | apple=orange | banana }}

	$options = extractOptions( array_slice( func_get_args(), 1 ) );

	// Now you've got an array that looks like this:
	// [foo] => 'bar'
	// [apple] => 'orange'
	// [banana] => true
	// Continue writing your code...
}

/**
 * Converts an array of values in form [0] => "name=value"
 * into a real associative array in form [name] => value
 * If no = is provided, true is assumed like this: [name] => true
 *
 * @param array string $options
 * @return array $results
 */
function extractOptions( array $options ) {
	$results = [];
	foreach ( $options as $option ) {
		$pair = array_map( 'trim', explode( '=', $option, 2 ) );
		if ( count( $pair ) === 2 ) {
			$results[ $pair[0] ] = $pair[1];
		}
		if ( count( $pair ) === 1 ) {
			$results[ $pair[0] ] = true;
		}
	}
	return $results;
}

関連かんれん項目こうもく

General and related guides:

• Manual:拡張かくちょう機能きのうの開発かいはつ , or for more general information about extensions, see Manual:拡張かくちょう機能きのう and 拡張かくちょう機能きのうのよくある質問しつもん .
• Manual:タグ拡張かくちょう機能きのう
• Manual:マジックワード

Code:

• Manual:Parser.php
• Manual:フック/ParserFirstCallInit
• Parser function hooks - an (incomplete) list of parser functions provided by core and extensions
• パーサー フック PHP ライブラリ - 宣言せんげん型がたパーサーフックのためのオブジェクト指向しこうインターフェイスを提供ていきょうする
• Manual:Extension data

Examples:

• ParserFunctions 拡張かくちょう機能きのうは、よく知しられたパーサー関数かんすうのコレクションです。
• Help:Extension:ParserFunctions
• Category:Parser function extensions[[::Category:Parser function extensions| ]]