Wikipedia:Panduan Scribble

"Shh! Saya sedang membaca bagaimana mahu scribble templat"

Ini ialah Panduan berkenaan Scribbling. Scribbling merujuk kepada tindakan menulis, ataupun mengubah, templat yang menggunakan penyambung Scribunto MediaWiki yang dibangunkan Tim Starling dan Victor Vasiliev. "Scribunto" datang daripada bahasa Latin yang bermaksud, "mereka akan menulis". Panduan ini bertujuan untuk memberi anda gambaran am Scribble dan beberapa petunjuk kepada maklumat lanjut tentangnya.

Templat Scribble mengandungi dua bahagian: templat itu sendiri dan satu atau lebih "modul" bahagian belakang yang terdapat dalam ruang nama Modul: yang mengandungi atur cara yang dilaksanakan pada pelayan wiki bagi menjana teks wiki yang dikembangkan daripada templat. Templat mencetuskan suatu fungsi yang terkandung dalam modul dengan menggunakan fungsi penghurai bernama {{#invoke:}}.

Scribble bertujuan untuk meningkatkan prestasi pemprosesan templat. Scribble menghilangkan keperluan bagi pengaturcaraan fungsi penghuraian templat melalui penggunaan fungsi penghurai seperti {{#if:}}, {{#ifeq:}}, {{#switch:}}, dan {{#eval:}}. Sebaliknya semua ini dilakukan dalam modul, dalam bahasa yang sebenarnya direka sebagai bahasa pengaturcaraan berbanding sistem templat yang ditokok tambah agar menjadi satu bahasa pengaturcaraan. Scribble juga menghilangkan keperluan untuk templat yang mengembangkan templat lain dan berkemungkinan sampai ke had pengembangan. Templat Scribble seharusnya tidak akan memerlukan transklusi templat lain.

Lua

Bahasa yang digunakan bagi menulis modul ialah Lua. Berlainan dengan sistem fungsi penghurai, Lua bukan sahaja direka sebagai bahasa pengaturcaraan, ia juga merupakan bahasa yang amat sesuai untuk apa yang digelar penskripan terbenam. Modul-modul MediaWiki merupakan contoh skrip-skrip yang terbenam. Ada beberapa bahasa penskripan terbenam yang dapat digunakan, termasuk REXX dan tcl; dan sesungguhnya tujuan asal Scribunto adalah untuk menyediakan pilihan bahasa, namun buat masa ini hanya Lua disediakan.

Manual rujukan rasmi Lua ialah Ierusalimschy, de Figueiredo & Celes 2006. Ia sebuah rujukan, bukan tutorial. Rujuklah ia jika anda mahu tahu sintaks atau semantik dan sebagainya. Untuk tutorial, baca sama ada Ierusalimschy 2006 (Ierusalimschy 2003 juga ada, tetapi ia sudah lapuk) ataupun Jung & Brown 2007. Masalah dengan buku-buku ini ialah banyak yang diperkatakan dalamnya tidak ada kaitan dengan modul-modul MediaWiki. Anda tidak perlu tahu bagaimana memasang Lua and menyepadukan pentafsirnya ke dalam program atau menjalankanya secara tersendiri. Para pembangun MediaWiki sudah melakukan semua itu. Sama juga, banyak perpustakaan fungsi Lua tidak disediakan atas sebab keselamatan. (Sebagai contoh, pengguna MediaWiki tidak dapat membuat I/O fail atau membuat penggilan sistem operasi dalam modul MediaWiki.) Jadi, banyak perkara yang dinyatakan dalam bulu tentang fungsi-fungsi perpustakaan piawai Lua dan pemboleh ubah tidak relevan ataupun tidak betul dalam kes MediaWiki.

Spesifikasi asal API — fungsi-fungsi perpustakaan piawai dan pemboleh ubah yang sepatutnya terdapat pada modul-modul — diberikan dalam MW:Extension:Scribunto/spesifikasi API. Walau bagaimanapun, itu pun tidak berapa betul. Apa yang sebenarnya disediakan dicatat dalam MW:Extension:Scribunto/manual rujukan Lua, yang merupakan versi ringkasan Edisi Pertama manual Lua yang sudah disunting dan diubah suai Tim Starling agar lebih sesuai dengan Scribble. Sekali lagi perlu dinyatakan bahawa ia sebuah manual rujukan, bukan tutorial.

Apabila menulis templat Scribble, perkara-perkara Lua yang berkaitan ialah tables (jadual), strings (rentetan), numbers (angka/nombor), booleans (ungkapan Boolean), struktur kawalan termasuk nil, if … then … else … end, while … do … end, for … in … do … end (for yang dijana), for … do … end (numerical for), repeat … until, function … end, local, return, break, ungkapan dan pelbagai operator (termasuk #, .., operator hisab +, -, *, /, ^, dan %), dan juga string, math, dan jadual sejagat mw (yakni, perpustakaan).

Struktur templat

Ini mudah. Dalam kes biasa, templat anda merangkumi satu pengembangan {{#invoke:}}. Ini {{ref label}} sebagai contoh:

<includeonly>{{#invoke:citation|reflabel}}</includeonly><noinclude>{{documentation}}</noinclude>

Malah, {{Harvard citation}}, satu daripada templat Scribble yang terpanjang, masih kekal sebagai satu pengembangan {{#invoke:}}:

<includeonly>{{#invoke:citation|Harvard
|BracketLeft=(
|BracketRight=)
|PageSep=, p.&nbsp;
|PagesSep=, pp.&nbsp;
}}</includeonly><noinclude>{{documentation}}</noinclude>

Jika anda mendapati bahawa anda perlu menggunakan templat lain dalam templat anda, ataupun menggunakan fungsi penghurai templat, malah apa pun selain daripada {{#invoke:}} dan mungkin sedikit pemboleh ubah sebagai argumennya, anda menggunakan pendekatan silap.

Asas-asas modul

Struktur keseluruhan

Mari kita pertimbangkan satu modul hipotesis, Module:Population. Modul ini dapat dibina dengan satu daripada dua cara:

Jadual lokal yang ternama

local p = {}

function p.India(frame)
    return "1,21,01,93,422 people at (nominally) 2011-03-01 00:00:00 +0530"
end

return p

Jadual tak ternama yang dijana secara layang

return {
    India = function(frame)
        return "1,21,01,93,422 people at (nominally) 2011-03-01 00:00:00 +0530"
    end
}

Pelaksanaan

Pelaksanaan modul oleh {{#invoke:}} sebenarnya berlapis dua:

1. Modul dimuatkan dan seluruh skrip dilaksana. Ini memuatkan modul-modul tambahan yang diperlukan modul (melalui fungsi require()), membina fungsi-fungsi (yang tidak boleh dipanggil, uninvocable) yang disediakan modul buat templat-templat, dan memulangkan satu jadual fungsi-fungsi tersebut.
2. Fungsi yang disebut dalam {{#invoke:}} dipilih daripada jadual yang terbina dalam fasa 1, dan dipanggil dengan argumen-argumen disediakan kepada templat, dan argumen-argumen yang dibekalkan kepada {{#invoke:}} (perincian diberi kemudian).

Skrip Lua pertama melaksanakan fasa 1 dengan cara yang agak nyata. Ia membuat pemboleh ubah lokal ternama p pada baris 1, yang mengasalnya (initialize) pada sebuah jadual; membina dan menambah fungsi padanya (baris 3–5), dengan memberi fungsi nama India dalam jadual yang dinamakan p (function p.India sama dengan berkata p["India"] = function); dan kemudian memulangkan (baris 7) jadual sebagai baris terakhir skrip. Untuk mengembangkan skrip dengan fungsi-fungsi (tidak boleh dipanggil), kita perlu menulis fungsi-fungsi tersebut di antara kenyataan local pada bahagian atas dan kenyataan return pada bahagian bawah. (Fungsi-fungsi lokal yang boleh dipanggil (non-invocable) boleh ditambah sebelum kenyataan local.) Pemboleh ubah lokal tidak perlu diberi nama p. Ia boleh diberi apa jua nama sah pemboleh ubah Lua yang anda suka. Untuk tujuan ini, p hanya resam, dan juga nama yang anda boleh guna untuk menguji skrip pada konsol nyahpepijat alat penyunting Modul.

Skrip Lua kedua membuat perkara yang sama, tetapi dengan cara yang lebih "idiomatik". Ia tidak menjana pemboleh ubuh ternama sebagai jadual, tetapi sebaliknya menjana jadual awanama layang, ditengah-tengah kenyataan return, yang merupakan kenyataan tunggal (dilaksanakan dalam fasa pertama) skrip. India = function(frame) … end pada baris 2–4 membuat fungsi (juga awanama) dan menyelitkannya ke dalam jadual di bawah nama India. Untuk mengembangkan skrip dengan fungsi-fungsi (tidak boleh dipanggil), kita tambah fungsi-fungsi tersebut sebagai medan tambahan dalam jadual. (Fungsi-fungsi lokal tidak boleh dipanggil dapat sekali lagi ditambah sebelum kenyataan return.)

Dalam kedua-dua kes, kod templat yang ditulis ialah {{#invoke:Population|India}} bagi memanggil (invoke) fungsi ternama India daripada modul Module:Population. Juga perhatikan yang function membina sesuatu fungsi, sebagai sebuah objek yang dipanggil. Ia tidak mengisytiharkan fungsi seperti yang dijangka berlaku dengan bahasa-bahasa lain, dan fungsi tidak dilaksanakan sehinggalah ia dipanggil.

Sudah tentunya kita dapat membuat perkara yang lebih kompleks daripada ini. Sebagai contoh: Kita boleh membuat perisytiharan pemboleh ubah lokal lain sebagai tambahan kepada p, bagi memegang jadual-jadual data (seperti senarai Bahasa atau nama-nama negara), yang digunakan modul. Akan tetapi bahagian ini adalah berkaitan struktur asas modul. Anda boleh membuat jadual yang penuh dengan bahan, dan memulangkannya.

Menerima argumen templat

Fungsi biasa Lua dapat mengambil (secara hakikatnya) sembarangan bilangan argumen. Lihat fungsi Modul:Wikitext yang boleh dipanggil dengan sifar sehingga tiga argumen:

function z.oxfordlist(args,separator,ampersand)

Fungsi-fungsi yang dipanggil {{#invoke:}} adalah istimewa. Fungsi-fungsi ini menjangka akan diberi hanya satu argumen, satu jadual yang digelar frame (dan secara resamnya diberi nama parameter frame dalam senarai parameter fungsi). Ia disebut frame (kerangka) kerana, malangnya, para pembangun memilih nama itu buat kesenangan mereka. Ia dinamakan sempena struktur dalaman kod MediaWiki sendiri yang lebih kurang diwakili "frame".

Frame atau kerangka ini memiliki dua (sub)jadual dalamnya, dipanggil args. Ia juga memiliki cara untuk mengakses kerangka induk atau parent frame (sekali lagi dinamakan sempena sesuatu dalam MediaWiki). Kerangka induk ini juga mempunyai (sub)jadual dalamnya, juga diberi nama args.

• Argumen-argumen dalam "frame" (anak, kita kira) — iaitu nilai parameter frame pada fungsi — ialah argumen yang dikirim kepada {{#invoke:}} dalam teks wiki templat anda. Jadi, sebagai contoh, sekiranya anda menulis {{#invoke:Population|India|a|b|class="popdata"}} dalam templat anda, subjadual argumen-argumen kerangka anak akan ditulis (dalam bentuk Lua) demikian rupa: { "a", "b", class="popdata" }.
• Argumen-argumen dalam kerangka induk ialah argumen-argumen yang dikirim kepada templat anda apabila ia ditransklusi. Justeru, sebagai contoh, sekiranya pengguna templat anda menulis {{Population of India|c|d|language=Hindi}}, subjadual argumen kerangka induk akan ditulis dalam bentuk Lua begini: { "c", "d", language="Hindi" }.

Satu idiom pengatur cara yang dapat anda guna bagi memudahkan semua ini ialah mengadakan pemboleh ubah lokal config dan args dalam fungsi anda yang menunjuk kepada kedua-dua jadual argumen ini. Lihat ini pada Modul:Citation:

-- This is used by template {{efn}}.
function z.efn(frame)
    local pframe = frame:getParent()
    local config = frame.args -- the arguments passed BY the template, in the wikitext of the template itself
    local args = pframe.args -- the arguments passed TO the template, in the wikitext that transcludes the template

Ralat

Mari kita bereskan sesuatu awal-awal lagi: Ralat skrip ialah hiperpautan. Anda boleh meletakkan kursor tetikus padanya dan petik.

Kita sudah menjadi biasa dengan templat-templat (bukan Scribble) kita yang menampilkan pesanan-pesanan ralat berwarna merah sehingga kita fikir yang pesanan "ralat skrip" Scribunto pun sama. Tidak. Jika anda menghidupkan JavaScript dalam pelayar, ia akan menimbulkan tetingkap yang memerikan perincian ralat, kesan balik panggilan ( call backtrace) dan juga pautan yang akan membawa anda ke lokasi kod ralat dalam modul berkaitan.

Anda boleh menimbulkan ralat dengan memanggil fungsi error().