Lihat sumber bagi Modul:Arguments/doc

{{High-risk| 15,000,000+ }}

Modul ini menyediakan pemprosesan argumen yang mudah dihantar dari #invoke. Ini adalah meta-modul, yang dimaksudkan untuk digunakan oleh modul lain, dan tidak boleh dipanggil langsung dari #invoke. Ciri-cirinya merangkumi:
* Pemangkasan argumen dan penghapusan argumen kosong dengan mudah.
* Argumen dapat dilalui oleh bingkai semasa dan bingkai induk pada masa yang sama. (Maklumat lebih lanjut di bawah.)
* Argumen boleh disampaikan terus dari modul Lua lain atau dari konsol debug.
* Argumen diambil mengikut keperluan, yang dapat membantu mengelakkan (beberapa) masalah dengan tag {{tag|ref}}.
* Sebilangan besar ciri boleh disesuaikan.

== Penggunaan asas ==

Pertama, anda perlu memuatkan modul. Ia mengandungi satu fungsi, yang dinamakan <code>getArgs</code>.

<source lang="lua">
local getArgs = require('Modul:Arguments').getArgs
</source>

Dalam senario paling asas, anda boleh menggunakan getArgs di dalam fungsi utama anda. Pemboleh ubah <code>args</code> adalah meja/jadual yang mengandungi hujah dari #invoke. (Lihat di bawah untuk maklumat lanjut.)

<source lang="lua">
local getArgs = require('Modul:Arguments').getArgs
local p = {}

function p.main(frame)
	local args = getArgs(frame)
	-- Main module code goes here.
end

return p
</source>

Walau bagaimanapun, amalan yang disarankan adalah menggunakan fungsi hanya untuk memproses argumen dari #invoke. Ini bermaksud bahawa jika seseorang memanggil modul anda dari modul Lua yang lain, anda tidak perlu menyediakan objek bingkai, yang meningkatkan prestasi.

<source lang="lua">
local getArgs = require('Modul:Arguments').getArgs
local p = {}

function p.main(frame)
	local args = getArgs(frame)
	return p._main(args)
end

function p._main(args)
	-- Main module code goes here.
end

return p
</source>

Sekiranya anda mahu beberapa fungsi menggunakan argumen, dan anda juga mahu fungsi tersebut dapat diakses dari #invoke, anda boleh menggunakan fungsi pembalut.

<source lang="lua">
local getArgs = require('Modul:Arguments').getArgs

local function makeInvokeFunc(funcName)
	return function (frame)
		local args = getArgs(frame)
		return p[funcName](args)
	end
end

local p = {}

p.func1 = makeInvokeFunc('_func1')

function p._func1(args)
	-- Code for the first function goes here.
end

p.func2 = makeInvokeFunc('_func2')

function p._func2(args)
	-- Code for the second function goes here.
end

return p
</source>

=== Pilihan ===

Pilihan berikut ada. Ianya dijelaskan dalam bahagian di bawah.

<source lang="lua">
local args = getArgs(frame, {
	trim = false,
	removeBlanks = false,
	valueFunc = function (key, value)
		-- Code for processing one argument
	end,
	frameOnly = true,
	parentOnly = true,
	parentFirst = true,
	wrappers = {
		'Templat:A wrapper template',
		'Templat:Another wrapper template'
	},
	readOnly = true,
	noOverwrite = true
})
</source>

=== Memotong dan mengeluarkan kosong ===

Argumen kosong sering kali membuat pengekod baru untuk menukar templat MediaWiki ke Lua. Dalam sintaks templat, rentetan dan rentetan kosong yang hanya terdiri daripada ruang kosong dianggap salah. Namun, di Lua, tali dan tali kosong yang terdiri daripada ruang kosong dianggap benar. Ini bermaksud bahawa jika anda tidak memperhatikan hujah-hujah tersebut semasa anda menulis modul Lua anda, anda mungkin memperlakukan sesuatu yang benar yang sebenarnya harus dianggap sebagai salah. Untuk mengelakkannya, secara lalai modul ini membuang semua argumen kosong.

Begitu juga, ruang kosong boleh menyebabkan masalah ketika berhadapan dengan posisi argumen. Walaupun ruang kosong dipangkas untuk argumen bernama yang berasal #invoke, ia disimpan untuk posisi argumen. Selalunya ruang kosong tambahan ini tidak diingini, jadi modul ini memotongnya secara lalai.

Walau bagaimanapun, kadang-kadang anda mahu menggunakan argumen kosong sebagai input, dan kadang-kadang anda mahu mengekalkan ruang kosong tambahan. Ini boleh menjadi perlu untuk menukar beberapa templat anda sama seperti yang ditulis. Sekiranya anda mahu melakukan ini, anda boleh menetapkan <code>trim</code> dan <code>removeBlanks</code> argumen kepada <code>false</code>.

<source lang="lua">
local args = getArgs(frame, {
	trim = false,
	removeBlanks = false
})
</source>

=== Pemformatan argumen khusus ===

Kadang-kadang anda ingin membuang beberapa argumen kosong tetapi tidak yang lain, atau mungkin anda mungkin mahu meletakkan semua posisi argumen dengan huruf kecil. Untuk melakukan perkara seperti ini, anda boleh menggunakan pilihan <code>valueFunc</code>. Input untuk pilihan ini mestilah fungsi yang mengambil dua parameter, <code>key</code> dan <code>value</code>, dan mengembalikan satu nilai. Nilai ini adalah apa yang akan anda perolehi semasa anda memasuki lapangan <code>key</code> dalam <code>args</code> meja/jadual.

Contoh 1: fungsi ini mengekalkan ruang kosong untuk argumen kedudukan pertama, tetapi memotong semua argumen lain dan membuang semua argumen kosong yang lain.
<source lang="lua">
local args = getArgs(frame, {
	valueFunc = function (key, value)
		if key == 1 then
			return value
		elseif value then
			value = mw.text.trim(value)
			if value ~= '' then
				return value
			end
		end
		return nil
	end
})
</source>

Contoh 2: fungsi ini membuang argumen kosong dan menukar semua argumen menjadi huruf kecil, tetapi tidak memotong ruang kosong dari posisi parameter.
<source lang="lua">
local args = getArgs(frame, {
	valueFunc = function (key, value)
		if not value then
			return nil
		end
		value = mw.ustring.lower(value)
		if mw.ustring.find(value, '%S') then
			return value
		end
		return nil
	end
})
</source>

Nota: fungsi di atas akan gagal sekiranya input yang dikeluarkan bukan jenis <code>string</code> atau <code>nil</code>. Ini mungkin berlaku jika anda menggunakan fungsi <code>getArgs</code> dalam fungsi utama modul anda, dan fungsi itu dipanggil oleh modul Lua yang lain. Dalam kes ini, anda perlu memeriksa jenis input anda. Ini tidak menjadi masalah jika anda menggunakan fungsi khas untuk argumen dari #invoke (iaitu anda perlu fungsi <code>p.main</code> dan <code>p._main</code>, atau yang serupa).

{{cot|Contoh 1 dan 2 dengan jenis pemeriksaan}}
Contoh 1:
<source lang="lua">
local args = getArgs(frame, {
	valueFunc = function (key, value)
		if key == 1 then
			return value
		elseif type(value) == 'string' then
			value = mw.text.trim(value)
			if value ~= '' then
				return value
			else
				return nil
			end
		else
			return value
		end
	end
})
</source>

Contoh 2:
<source lang="lua">
local args = getArgs(frame, {
	valueFunc = function (key, value)
		if type(value) == 'string' then
			value = mw.ustring.lower(value)
			if mw.ustring.find(value, '%S') then
				return value
			else
				return nil
			end
		else
			return value
		end
	end
})
</source>
{{cob}}

Juga, harap maklum bahawa fungsi <code>valueFunc</code> dipanggil lebih kurang setiap kali argumen diminta dari meja/jadual <code>args</code>, jadi jika anda mementingkan prestasi, anda harus memastikan bahawa anda tidak melakukan sesuatu yang tidak cekap dengan kod anda.

=== Bingkai dan bingkai induk (parent) ===

Argumen dalam <code>args</code> meja/jadual boleh dilalui dari bingkai semasa atau dari bingkai induknya pada masa yang sama. Untuk memahami maksudnya, adalah paling mudah untuk memberi contoh. Katakan bahawa kita mempunyai modul yang dipanggil <code>Modul:ExampleArgs</code>. Modul ini mencetak dua argumen kedudukan pertama yang diluluskan.

{{cot|Modul:Kod ContohArgs}}
<source lang="lua">
local getArgs = require('Modul:Arguments').getArgs
local p = {}

function p.main(frame)
	local args = getArgs(frame)
	return p._main(args)
end

function p._main(args)
	local first = args[1] or ''
	local second = args[2] or ''
	return first .. ' ' .. second
end

return p
</source>
{{cob}}

<code>Modul:ExampleArgs</code> kemudian dipanggil oleh <code>Templat:ExampleArgs</code>, yang mengandungi kod <code><nowiki>{{#invoke:ExampleArgs|main|firstInvokeArg}}</nowiki></code>. Ini menghasilkan keputusan "firstInvokeArg".

Sekarang jika kita memanggil <code>Templat:ExampleArgs</code>, perkara berikut akan berlaku:

{| class="wikitable" style="width: 50em; max-width: 100%;"
|-
! style="width: 60%;" | Kod
! style="width: 40%;" | Keputusan
|-
| <code><nowiki>{{ExampleArgs}}</nowiki></code>
| firstInvokeArg
|-
| <code><nowiki>{{ExampleArgs|firstTemplateArg}}</nowiki></code>
| firstInvokeArg
|-
| <code><nowiki>{{ExampleArgs|firstTemplateArg|secondTemplateArg}}</nowiki></code>
| firstInvokeArg secondTemplateArg
|}

Terdapat tiga pilihan yang boleh anda tetapkan untuk mengubah tingkah laku ini:<code>frameOnly</code>, <code>parentOnly</code> dan <code>parentFirst</code>. Jika anda menetapkan <code>frameOnly</code> maka hanya argumen yang diluluskan dari kerangka semasa yang akan diterima; jika anda menetapkan <code>parentOnly</code> maka hanya argumen yang dikeluarkan dari bingkai induk yang akan diterima; dan jika anda menetapkan <code>parentFirst</code> maka argumen akan dilalui dari kedua-dua bingkai semasa dan induk, tetapi bingkai induk akan mempunyai keutamaan daripada bingkai semasa. Berikut adalah hasil dari segi <code>Templat:ExampleArgs</code>:

; frameOnly
{| class="wikitable" style="width: 50em; max-width: 100%;"
|-
! style="width: 60%;" | Kod
! style="width: 40%;" | Keputusan
|-
| <code><nowiki>{{ExampleArgs}}</nowiki></code>
| firstInvokeArg
|-
| <code><nowiki>{{ExampleArgs|firstTemplateArg}}</nowiki></code>
| firstInvokeArg
|-
| <code><nowiki>{{ExampleArgs|firstTemplateArg|secondTemplateArg}}</nowiki></code>
| firstInvokeArg
|}

; parentOnly
{| class="wikitable" style="width: 50em; max-width: 100%;"
|-
! style="width: 60%;" | Kod
! style="width: 40%;" | Keputusan
|-
| <code><nowiki>{{ExampleArgs}}</nowiki></code>
| 
|-
| <code><nowiki>{{ExampleArgs|firstTemplateArg}}</nowiki></code>
| firstTemplateArg
|-
| <code><nowiki>{{ExampleArgs|firstTemplateArg|secondTemplateArg}}</nowiki></code>
| firstTemplateArg secondTemplateArg
|}

; parentFirst
{| class="wikitable" style="width: 50em; max-width: 100%;"
|-
! style="width: 60%;" | Kod
! style="width: 40%;" | Keputusan
|-
| <code><nowiki>{{ExampleArgs}}</nowiki></code>
| firstInvokeArg
|-
| <code><nowiki>{{ExampleArgs|firstTemplateArg}}</nowiki></code>
| firstTemplateArg
|-
| <code><nowiki>{{ExampleArgs|firstTemplateArg|secondTemplateArg}}</nowiki></code>
| firstTemplateArg secondTemplateArg
|}

Nota:
# Jika anda menetapkan kedua-dua pilihan <code>frameOnly</code> dan <code>parentOnly</code>, modul tidak akan sama sekali mengeluarkan argumen dari #invoke. Ini mungkin bukan yang anda mahukan.
# Dalam beberapa keadaan, bingkai induk mungkin tidak tersedia, cth. jika getArgs diluluskan bingkai induk bukan bingkai semasa. Dalam kes ini, hanya kerangka argumen yang akan digunakan (kecuali jika parentOnly ditetapkan, dalam hal ini tidak ada argumen yang akan digunakan) dan pilihan <code>parentFirst</code> dan <code>frameOnly</code> tidak akan memberi kesan..

=== Wrappers ===

The ''wrappers'' option is used to specify a limited number of templates as ''wrapper templates'', that is, templates whose only purpose is to call a module. If the module detects that it is being called from a wrapper template, it will only check for arguments in the parent frame; otherwise it will only check for arguments in the frame passed to getArgs. This allows modules to be called by either #invoke or through a wrapper template without the loss of performance associated with having to check both the frame and the parent frame for each argument lookup.

For example, the only content of [[Template:Side box]] (excluding content in {{tag|noinclude}} tags) is <code><nowiki>{{#invoke:Side box|main}}</nowiki></code>. There is no point in checking the arguments passed directly to the #invoke statement for this template, as no arguments will ever be specified there. We can avoid checking arguments passed to #invoke by using the ''parentOnly'' option, but if we do this then #invoke will not work from other pages either. If this were the case, the {{para|text|Some text}} in the code <code><nowiki>{{#invoke:Side box|main|text=Some text}}</nowiki></code> would be ignored completely, no matter what page it was used from. By using the <code>wrappers</code> option to specify 'Template:Side box' as a wrapper, we can make <code><nowiki>{{#invoke:Side box|main|text=Some text}}</nowiki></code> work from most pages, while still not requiring that the module check for arguments on the [[Template:Side box]] page itself.

Wrappers can be specified either as a string, or as an array of strings.

<source lang="lua">
local args = getArgs(frame, {
	wrappers = 'Template:Wrapper template'
})
</source>


<source lang="lua">
local args = getArgs(frame, {
	wrappers = {
		'Template:Wrapper 1',
		'Template:Wrapper 2',
		-- Any number of wrapper templates can be added here.
	}
})
</source>

Notes:
# The module will automatically detect if it is being called from a wrapper template's /sandbox subpage, so there is no need to specify sandbox pages explicitly.
# The ''wrappers'' option effectively changes the default of the ''frameOnly'' and ''parentOnly'' options. If, for example, ''parentOnly'' were explicitly set to false with ''wrappers'' set, calls via wrapper templates would result in both frame and parent arguments being loaded, though calls not via wrapper templates would result in only frame arguments being loaded.
# If the ''wrappers'' option is set and no parent frame is available, the module will always get the arguments from the frame passed to <code>getArgs</code>.

=== Menulis di meja/jadual args ===

Kadang-kadang berguna untuk menulis nilai baru ke meja/jadual args. Ini mungkin dilakukan dengan tetapan lalai modul ini. (Namun, ingatlah bahawa gaya pengkodan biasanya lebih baik untuk membuat jadual baru dengan nilai baru anda dan menyalin argumen dari jadual argumen jika diperlukan.)

<source lang="lua">
args.foo = 'some value'
</source>

Adalah mungkin untuk mengubah tingkah laku ini dengan pilihan <code>readOnly</code> dan <code>noOverwrite</code>. Jika <code>readOnly</code> diatur maka tidak mustahil untuk menulis nilai ke meja/jadual argumen sama sekali. Jika <code>noOverwrite</code> ditetapkan, maka ia adalah mungkin untuk menambah nilai-nilai baru ke meja/jadual, tetapi ia tidak mungkin untuk menambah nilai jika ia akan menulis ganti sebarang argumen yang diluluskan dari #invoke.

=== Ref tags ===

This module uses [[mw:Extension:Scribunto/Lua reference manual#Metatables|metatables]] to fetch arguments from #invoke. This allows access to both the frame arguments and the parent frame arguments without using the <code>pairs()</code> function. This can help if your module might be passed {{tag|ref}} tags as input.

As soon as {{tag|ref}} tags are accessed from Lua, they are processed by the MediaWiki software and the reference will appear in the reference list at the bottom of the article. If your module proceeds to omit the reference tag from the output, you will end up with a phantom reference - a reference that appears in the reference list, but no number that links to it. This has been a problem with modules that use <code>pairs()</code> to detect whether to use the arguments from the frame or the parent frame, as those modules automatically process every available argument.

This module solves this problem by allowing access to both frame and parent frame arguments, while still only fetching those arguments when it is necessary. The problem will still occur if you use <code>pairs(args)</code> elsewhere in your module, however.

=== Batasan yang diketahui ===

Penggunaan metatables juga mempunyai kelemahannya. Sebilangan besar alat meja Lua biasa tidak akan berfungsi dengan baik di meja args, termasuk operasi fungsi <code>#</code>, <code>next()</code>, dan fungsi di perpustakaan meja/jadual. Sekiranya menggunakan ini penting untuk modul anda, anda harus menggunakan fungsi pemprosesan argumen anda sendiri dan bukannya modul ini.<includeonly>{{#ifeq:{{SUBPAGENAME}}|sandbox||
[[Kategori:Metamodul Lua]]
}}</includeonly>