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

From mediawiki.org
This page is a translated version of the page Manual:Parser functions and the translation is 99% complete.
MediaWiki extensions

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

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

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

Önbelleğe almak

Etiket uzantılarında olduğu gibi, dinamik uzantılar için önbelleği devre dışı bırakmak için $parser->disableCache() kullanılabilir. (1.28 sürümünde kaldırıldı)

Bunun performans üzerinde önemli bir olumsuz etkisi vardır, bu nedenle yalnızca gerektiğinde kullanın.

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

Ancak,

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

şöyle bir şey üretecek:

This is
param1 merhaba ve param2 selam ve param3 hey bir test.

Bu, ayrıştırıcı işlevlerinin HTML çıkışının başına eklenen sabit kodlanmış bir "\n\n" nedeniyle olur. Bundan kaçınmak ve HTML kodunun çevreleyen metne satır içi olarak işlendiğinden emin olmak için şunu kullanabilirsiniz:

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

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.

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:

found
Döndürülen metin geçerlidir, şablonu işlemeyi bırakın. Bu varsayılan olarak açıktır.
nowiki
return değerindeki viki işaretlemesinden kaçınılmalıdır
noparse
Güvenli olmayan HTML etiketleri çıkarılmamalı, vb.
noargs
Dönüş değerinde üç ayraçlı bağımsız değişkenleri değiştirmeyin
isHTML
Döndürülen metin HTML'dir, onu vikimetin dönüşümüne karşı korur

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