Manual:Ayrıştırıcı işlevleri

MediaWiki 1.7'de eklenen ayrıştırıcı işlevleri, ayrıştırıcıyla yakından bütünleşen bir uzantı türüdür. "Ayrıştırıcı işlevi" ifadesi, basit ayrıştırıcı işlevlerin bir koleksiyonu olan Extension:ParserFunctions ile karıştırılmamalıdır. (Bunlar için Help:Extension:ParserFunctions sayfasına bakın.)

Açıklama

Bir etiket uzantısının işlenmemiş metni alması ve tarayıcıya HTML döndürmesi beklenirken, bir ayrıştırıcı işlevi sayfadaki diğer viki ögeleriyle'etkileşime girebilir. Örneğin, bir ayrıştırıcı işlevinin çıkışı bir şablon parametresi olarak veya bir bağlantı yapımında kullanılabilir.

Bir ayrıştırıcı işlevi için tipik sözdizimi şöyledir:

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

Daha fazla bilgi için Parser::setFunctionHook ( $id, $callback, $flags = 0 ) için belgelendirmeye bakın. Bu belgelendirme şunları belirtir:

Geri çağırma işlevi şu şekilde olmalıdır:

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

Veya bununla SFH_OBJECT_ARGS:

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

Çağrının ilk çeşidi tüm bağımsız değişkenleri düz metin olarak iletir. 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. Bunlar, genişletilmemiş vikimetni temsil eder. The $frame parameter can be used to expand these arguments as needed. Bu, genellikle koşullu işleme için kullanılır, böylece yalnızca "true" durum, if veya switch benzeri bir ayrıştırıcı işleviyle değerlendirilir. Frame nesnesi ayrıca arayan hakkında bilgi almak için belge ağacına tırmanabilir ve çağrı derinliğini, yaşam süresini ve ayrıştırıcı işlevinin sonucunun geçici olup olmadığını belirleme ve yönetme işlevlerine sahiptir.

Ayrıştırıcı işlevi oluşturmak, yeni bir etiket oluşturmaktan biraz daha karmaşıktır çünkü işlev adı, takma adları ve yerelleştirmeyi destekleyen bir anahtar sözcük olan sihirli kelime olmalıdır.

Basit örnek

Aşağıda, ayrıştırıcı işlevi oluşturan bir uzantı örneği verilmiştir.

Kayıt, sırasıyla extension.json içine ve kod src/ExampleExtensionHooks.php içine gider:

{
	"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 {
   // Ayrıştırıcı ile herhangi bir işleme geri çağırmasını kaydedin
   public static function onParserFirstCallInit( Parser $parser ) {

      // "example" sihirli kelimesini renderExample() ile ilişkilendiren bir işlev kancası oluşturun
      $parser->setFunctionHook( 'example', [ self::class, 'renderExample' ] );
   }

   // {{#example:}} çıkışını oluşturun.
   public static function renderExample( Parser $parser, $param1 = '', $param2 = '', $param3 = '' ) {

      // Giriş parametreleri, şablonları genişletilmiş vikimetindir.
      // Çıkış da vikimetin olmalıdır.
      $output = "param1 is $param1 and param2 is $param2 and param3 is $param3";

      return $output;
   }
}

Uzantı dizininizdeki (src/ alt dizininde değil) başka bir dosya olan ExampleExtension.i18n.php şunları içermelidir:

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

$magicWords = [];

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

Bu uzantı etkinleştirildiğinde,

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

şunu üretir:

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

Bu magicWords dizisi isteğe bağlı değildir. Atlanırsa, ayrıştırıcı işlevi çalışmayacaktır; {{#example: hello | hi}}, uzantı yüklenmemiş gibi işlenecektir. 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. Sihirli kelimeleri bir i18n dosyası yerine PHP'de satır içi ilişkilendirebilirsiniz. Bu, LocalSettings.php içindeki kancaları tanımlarken kullanışlıdır.

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];
}

Daha uzun işlevler

Daha uzun işlevler için, kanca işlevlerini bir _body.php veya .hooks.php dosyasına bölmek ve bunları bir sınıfın statik işlevleri yapmak isteyebilirsiniz. Ardından sınıfı $wgAutoloadClasses ile yükleyebilir ve kancalardaki statik işlevleri çağırabilirsiniz; ör.:

Bunu extension.json dosyanıza koyun:

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

• Bakınız: diğer stiller için bir olay işleyicisi yazma.

Ardından bunu src/ExampleExtensionHooks.php dosyanıza koyun:

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

Ayrıştırıcı arayüzü

Çıkışnın ayrıştırılmasını kontrol etme

Ayrıştırıcı işleviniz tarafından döndürülen vikimetnin tamamen ayrıştırılması için (şablonların genişletilmesi dahil), dönerken noparse seçeneğini false olarak ayarlayın:

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

Görünüşe göre noparse için varsayılan değer false değerinden true değerine değişti, en azından bazı durumlarda, bazen 1.12 sürümü civarında.

Tersine, ayrıştırıcı işlevinizin vikimetni döndürmek yerine ayrıştırılmamış kalan HTML döndürmesini sağlamak için şunu kullanın:

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

Adlandırma

Varsayılan olarak, MW, her ayrıştırıcı işlevinin adına bir karma karakter (sayı işareti, "#") ekler. Bu eklemeyi bastırmak (ve "#" ön eki olmayan bir ayrıştırıcı işlevi elde etmek için), aşağıda açıklandığı gibi setFunctionHook ögenin isteğe bağlı flags bağımsız değişkenine SFH_NO_HASH sabitini dahil edin.

Karma öneki olmayan bir ad seçerken, bu işlev adıyla başlayan ve ardından iki nokta üst üste gelen bir ada sahip bir sayfanın dönüştürülmesinin artık mümkün olmadığını unutmayın. Özellikle, bir ad alanı adına eşit işlev adlarından kaçının. [1] vikiarası yansıtmanın etkinleştirilmesi durumunda, vikiarası önekine eşit işlev adlarından da kaçının.

setFunctionHook kancası

Ayrıştırıcıya ilişkin arabirimle ilgili daha fazla ayrıntı için, include/Parser.php içindeki setFunctionHook belgelendirmeyi bakın. İşte bu yorumların (muhtemelen tarihli) bir kopyası:

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

Parametreler:

• dize $id - Sihirli kelime kimliği
• karışık $callback - Kullanılacak geri çağırma işlevi (ve nesnesi)

• tamsayı $flags - İsteğe bağlı, işlevi "#" olmadan çağırmak için SFH_NO_HASH sabitine ayarlayın.

• SFH_NO_HASH (1) constant if you call the function without #.
• SFH_OBJECT_ARGS (2) if you pass a PPFrame object and array of arguments instead of a series of function arguments, for which see above.
• Defaults to 0 (no flags).

Dönüş değeri: Varsa bu ad için eski geri çağırma işlevi

Bir işlev oluşturun, örneğin {{#sum:1|2|3}}. Geri çağrı işlevi şu şekilde olmalıdır:

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

Geri çağrı, işlevin metin sonucunu veya 0 ögesindeki metni ve diğer ögelerde bir dizi bayrağı içeren bir diziyi döndürebilir. Bayrakların adları tuşlarda belirtilmiştir. Geçerli bayraklar şunlardır:

Name	Type	Default	Description
found	Boolean	true	Döndürülen metin geçerlidir, şablonu işlemeyi bırakın. Bu varsayılan olarak açıktır.
text	?	?	The text to return from the function. If isChildObj or isLocalObj are specified, this should be a DOM node instead.
noparse	Boolean	true	Güvenli olmayan HTML etiketleri çıkarılmamalı, vb.
isHTML	Boolean	?	Döndürülen metin HTML'dir, onu vikimetin dönüşümüne karşı korur But see discussion
nowiki	Boolean	usually false	return değerindeki viki işaretlemesinden kaçınılmalıdır
isChildObj	Boolean	?	true if the text is a DOM node needing expansion in a child frame.
isLocalObj	Boolean	?	true if the 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.

Adlandırılan parametreler

Ayrıştırıcı işlevleri, şablonların ve etiket uzantılarının yaptığı gibi adlandırılmış parametreleri desteklemez, ancak bazen onu taklit etmek yararlıdır. Kullanıcılar genellikle bağımsız değişkenleri ayırmak için dikey çubuklar ( | ) kullanmaya alışıktır, bu nedenle bunu ayrıştırıcı işlevi bağlamında da yapabilmek güzel. İşte bunun nasıl başarılacağına dair basit bir örnek:

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;
}

Ayrıca bakınız

General and related guides:

• Manual:Developing extensions , or for more general information about extensions, see Manual:Uzantılar and Extensions FAQ .
• Manual:Etiket uzantıları
• Manual:Sihirli kelimeler

Code:

• Manual:Parser.php
• Manual:Hooks/ParserFirstCallInit
• Parser function hooks - çekirdek ve uzantılar tarafından sağlanan ayrıştırıcı işlevlerinin (tamamlanmamış) bir listesi
• Bildirimsel ayrıştırıcı kancalar için nesne yönelimli bir arabirim sağlayan Ayrıştırıcı Kancaları PHP kitaplığı
• Manual:Extension data

Examples:

• ParserFunctions uzantısı, iyi bilinen bir ayrıştırıcı işlevleri koleksiyonudur.
• Help:Extension:ParserFunctions
• Category:Ayrıştırıcı işlev uzantıları[[::Category:Parser function extensions| ]]