Jump to content

Manual:Fungsi pengurai

From mediawiki.org
This page is a translated version of the page Manual:Parser functions and the translation is 98% complete.
Languages:
Kata-kata ajaib
MediaWiki extensions

Fungsi pengurai, yang ditambahkan dalam MediaWiki 1.7, adalah sejenis pengaya yang terpadu erat dengan pengurai. Frasa "fungsi pengurai" tidak boleh disamakan dengan Extension:ParserFunctions , yang merupakan kumpulan fungsi pengurai sederhana. (Lihat Bantuan:Ekstensi:ParserFunctions untuk itu.)

Deskripsi

Sementara pengaya tanda diharapkan mengambil teks yang tak terolah dan mengembalikan HTML ke peramban, fungsi pengurai dapat 'berinteraksi' dengan unsur wiki lain di halaman. Misalnya, keluaran fungsi pengurai dapat digunakan sebagai parameter templat atau dalam konstruksi tautan.

Sintaks umum untuk sebuah fungsi pengurai adalah:

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

Untuk informasi lainnya, lihat dokumentasi mengenai Parser::setFunctionHook ( $id, $callback, $flags = 0 ). Dokumentasi ini menyebutkan:

Fungsi panggilan balik harus memiliki bentuk:
function myParserFunction( $parser, $arg1, $arg2, $arg3 ) { ... }
Atau dengan SFH_OBJECT_ARGS:
function myParserFunction( $parser, $frame, $args ) { ... }

Varian pertama panggilan meneruskan semua argumen sebagai teks biasa. Yang kedua meneruskan semua argumen sebagai larik PPNode , kecuali yang pertama ($args[0]), yang saat ini berupa teks, meskipun ini dapat berubah di masa mendatang. Ini mewakili teks wiki yang tak diperluas. Parameter $frame dapat digunakan untuk memperluas argumen ini sesuai kebutuhan. Ini umumnya digunakan untuk pengolahan bersyarat sehingga hanya kasus true yang dinilai dengan fungsi pengurai if- atau switch-like. Objek bingkai juga dapat memanjat pohon dokumen untuk mendapatkan informasi tentang pemanggil dan memiliki fungsi untuk menentukan dan mengelola kedalaman panggilan, waktu hidup, dan apakah hasil fungsi pengurai bersifat volatil.

Membuat fungsi pengurai sedikit lebih rumit daripada membuat tanda baru karena nama fungsi harus berupa kata ajaib, kata kunci yang mendukung alias dan pelokalan.

Contoh sederhana

Di bawah ini adalah contoh pengaya yang membuat fungsi pengurai.

Pendaftarannya masuk ke extension.json, kode ke src/ExampleExtensionHooks.php:

Standard: Using the HookHandler interface:
extension.json 
{
	"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
}

{
	"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": "onParserFirstCallInit"
	},
	"HookHandlers": {
		"ExampleExtensionHooks": {
			"class": "MediaWiki\\Extension\\ExampleExtension\\Hooks"
		}
	},
	"manifest_version": 1
}
ExampleExtensionHooks.php 
<?php

class ExampleExtensionHooks {

   // Mendaftarkan panggilan balik render apa pun dengan pengurai
   public static function onParserFirstCallInit( Parser $parser ) {
      // Membuat pengait fungsi yang mengaitkan kata ajaib <code>example</code> dengan renderExample()
      $parser->setFunctionHook( 'example', [ self::class, 'renderExample' ] );
   }

   // Merender keluaran {{#example:}}.
   public static function renderExample( Parser $parser, $param1 = '', $param2 = '', $param3 = '' ) {
      // Parameter masukan berupa teks wiki dengan templat yang diperluas.
      // Keluarannya harus berupa teks wiki juga.
      $output = "param1 is $param1 and param2 is $param2 and param3 is $param3";

      return $output;
   }

}

<?php

class ExampleExtensionHooks implements ParserFirstCallInitHook {

   // Mendaftarkan panggilan balik render apa pun dengan parser
   public function onParserFirstCallInit( $parser ) {
      // Create a function hook associating the example magic word with renderExample()
      $parser->setFunctionHook( 'example', [ $this, 'renderExample' ] );
   }

   // Merender keluaran {{#example:}}.
   public function renderExample( $parser, $param1 = '', $param2 = '', $param3 = '' ) {
      // Parameter masukan berupa teks wiki dengan templat yang diperluas.
      // Keluarannya harus berupa teks wiki juga.
      $output = "param1 is $param1 and param2 is $param2 and param3 is $param3";
      return $output;
   }

}

Berkas lainnya, ExampleExtension.i18n.php, di direktori pengaya Anda (Bukan di subdirektori src/) harus mengandung: 

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

$magicWords = [];

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

Dengan pengaya ini dinyalakan,

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

menghasilkan:

  • param1 is hello and param2 is hi and param3 is hey
Larik magicWords ini tidak opsional. Jika dihilangkan, fungsi pengurai tidak akan bekerja; {{#example: hello | hi}} akan dirender seolah-olah pengaya tersebut tidak terpasang. Jika hanya larik khusus bahasa yang diinisialisasi dan bukan larik magicWords itu sendiri, ini dapat menyebabkan kesalahan pelokalan karena terjemahan dari pengaya lain bocor ke pengaya Anda. Anda dapat mengaitkan kata-kata ajaib sebaris dalam PHP daripada melalui berkas i18n. Ini berguna untuk menakrifkan pengait-pengait dalam LocalSettings.php 
MediaWiki\MediaWikiServices::getInstance()->getContentLanguage()->mMagicExtensions['wikicodeToHtml'] = ['MAG_CUSTOM', 'custom'];

Dalam LocalSettings.php

Kata-kata ajaib dan fungsi pengurai penanganannya dapat ditakrifkan sepenuhnya dalam 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];
}

Fungsi yang lebih panjang

Untuk fungsi yang lebih panjang, Anda mungkin ingin membagi fungsi pengait menjadi berkas _body.php atau .hooks.php dan menjadikannya fungsi statis dari suatu kelas. Kemudian, Anda dapat memuat kelas tersebut dengan $wgAutoloadClasses dan memanggil fungsi statis di dalam pengait; misalnya:

Taruh ini di berkas extension.json Anda: 

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

Lalu masukkan ini di berkas src/ExampleExtensionHooks.php Anda: 

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

Antarmuka pengurai

Mengendalikan penguraian keluaran

Agar teks wiki yang dikembalikan oleh fungsi pengurai Anda diurai sepenuhnya (termasuk perluasan templat), tetapkan pilihan noparse ke false saat mengembalikan: 

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

Tampaknya nilai bawaan untuk noparse berubah dari false menjadi true, setidaknya dalam beberapa keadaan, sekitar versi 1.12.

Sebaliknya, agar fungsi pengurai Anda mengembalikan HTML yang tidak diurai, daripada mengembalikan teks wiki, gunakan ini: 

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

Penamaan

Secara bawaan, MW menambahkan tanda pagar (tanda nomor, #) ke nama setiap fungsi pengurai. Untuk menghentikan penambahan tersebut (dan memperoleh fungsi pengurai tanpa awalan #), sertakan konstanta SFH_NO_HASH dalam argumen opsional flags hingga setFunctionHook, seperti dijelaskan di bawah.

Saat memilih nama tanpa awalan tagar, perlu diperhatikan bahwa transklusi halaman dengan nama yang dimulai dengan nama fungsi tersebut dan diikuti titik dua tidak lagi memungkinkan. Khususnya, hindari nama fungsi yang sama dengan nama sebuah ruang nama. Jika transklusi antarwiki [1] dinyalakan, hindari juga nama fungsi yang sama dengan awalan antarwiki.

Pengait setFunctionHook

Untuk rinciaan lebih mengenai antarmuka ke pengurai, lihat dokumentasi untuk setFunctionHook dalam includes/Parser.php. Berikut salinan komentar tersebut (yang mungkin sudah bertanggal):

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

Parameter:

  • string $id – Kata ajaib ID
  • mixed $callback – Fungsi panggilan balik (dan objek) yang akan digunakan
  • integer $flags – Opsional. Nilai:
  • SFH_NO_HASH (1) – konstan jika Anda memanggil fungsi tanpa #.
  • SFH_OBJECT_ARGS (2) – jika Anda meneruskan objek PPFrame dan larik argumen alih-alih serangkaian argumen fungsi, yang lihat di atas.
  • Tetapan bawaan ke 0 (tanpa bendera).

Nilai pengembalian: Fungsi panggilan balik lama untuk nama ini, jika ada

Buat sebuah fungsi, misalnya {{#sum:1|2|3}}. Fungsi panggilan baliknya harus berbentuk: 

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

Panggilan balik dapat mengembalikan hasil teks dari fungsi tersebut, atau larik dengan teks di unsur 0, dan sejumlah bendera di unsur lainnya. Nama-nama bendera ditentukan dalam kunci. Bendera yang sah adalah:

Nama Jenis Bawaan Deskripsi
found Boolean true true jika teks yang dikembalikan sah dan pengolahan templat harus dihentikan.
text ? ? Teks yang akan dikembalikan dari fungsi. Jika isChildObj atau isLocalObj ditentukan, ini seharusnya berupa simpul DOM.
noparse Boolean true true jika teks tidak boleh diolah terlebih dahulu menjadi pohon DOM, misalnya tanda HTML yang tak aman tidak boleh dihapus, dll.
isHTML Boolean ? true jika teks yang dikembalikan adalah HTML dan harus dilindungi terhadap pengubahan teks wiki Tapi lihat perbincangan
nowiki Boolean biasanya false true jika markah wiki dalam nilai yang dikembalikan (teks) harus dilarikan.
isChildObj Boolean ? true jika teksnya adalah simpul DOM yang memerlukan perluasan dalam bingkai anak.
isLocalObj Boolean ? true jika teksnya adalah simpul DOM yang memerlukan perluasan dalam bingkai saat ini. Nilai bawaan bergantung pada nilai dan hasil lainnya.
preprocessFlags ? false Bendera PPFrame opsional untuk digunakan saat mengurai teks yang dikembalikan. Ini hanya berlaku jika noparse adalah false.
title ? false Objek Title tempat teks itu berasal.
forceRawInterwiki Boolean ? true jika transklusi antarwiki harus dipaksakan dilakukan dalam mode mentah dan tidak dirender.

Fungsi pengurai mahal

Lihat pula: Manual:Template limits#Expensive parser function calls

Beberapa fungsi pengurai menunjukkan penggunaan sumber daya wiki yang lumayan besar dan harus ditandai sebagai "mahal". Jumlah fungsi pengurai mahal pada halaman tertentu dibatasi oleh pengaturan $wgExpensiveParserFunctionLimit . Apa yang dianggap mahal diserahkan ke fungsi itu sendiri, tetapi biasanya, apa pun yang mungkin menyebabkan penundaan yang melampaui pengolahan data sederhana harus dipertimbangkan. Ini termasuk hal-hal seperti pembacaan dan penulisan pangkalan data, peluncuran skrip cangkang secara sinkron, atau manipulasi berkas. Di sisi lain, tidak semua fungsi demikian harus diberi bendera. Semantic MediaWiki, misalnya, hanya menandai sebagian kecil pembacaan pangkalan datanya sebagai mahal. Ini disebabkan oleh fakta bahwa pada halaman-halaman tertentu yang padat data, fungsi pengurai mahal dapat dengan mudah melampaui batas normal. Dalam kasus seperti ini, potensi kinerja yang jauh lebih lambat namun tidak dibenderai mahal merupakan sebuah kerugian untuk memiliki fungsionalitas yang ditawarkan SMW.

Untuk menandai fungsi pengurai Anda sebagai mahal, dari dalam badan kode fungsi, gunakan $result = $parser->incrementExpensiveFunctionCount();. Nilai pengembalian akan menjadi false jika batas fungsi mahal telah tercapai atau terlampaui.

Parameter bernama

Fungsi pengurai tidak mendukung parameter bernama seperti yang didukung templat dan pengaya tanda, tetapi terkadang berguna untuk memalsukannya. Pengguna sering kali terbiasa menggunakan garis vertikal ( | ) untuk memisahkan argumen, jadi akan lebih baik jika hal itu juga dapat dilakukan dalam konteks fungsi pengurai. Berikut contoh sederhana cara melakukannya: 

function ExampleExtensionRenderParserFunction( &$parser ) {
	// Misalkan pengguna memanggil fungsi pengurai seperti ini:
	// {{#myparserfunction: foo=bar | apple=orange | banana }}

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

	// Sekarang Anda mendapat larik yang tampak begini:
	// [foo] => 'bar'
	// [apple] => 'orange'
	// [banana] => true
	// Terus menulis kode Anda...
}

/**
 * Mengonversi larik nilai dalam bentuk [0] => "nama=nilai"
 * ke dalam larik asosiatif nyata dalam bentuk [nama] => nilai
 * Jika tidak ada = yang diberikan, 'benar' dianggap seperti ini: [nama] => benar
 *
 * @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;
}

Lihat pula

Panduan umum dan terkait:

Kode:

Contoh:

Retrieved from "https://www.mediawiki.org/w/index.php?title=Manual:Parser_functions/id&oldid=8134419"