Modul:Arguments/doc

Daripada Wikipedia, ensiklopedia bebas.

Ini ialah laman pendokumenan untuk Modul:Arguments

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 <ref>...</ref>.
  • Sebilangan besar ciri boleh disesuaikan.

Penggunaan asas[sunting sumber]

Pertama, anda perlu memuatkan modul. Ia mengandungi satu fungsi, yang dinamakan getArgs.

local getArgs = require('Modul:Arguments').getArgs

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

local getArgs = require('Modul:Arguments').getArgs
local p = {}

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

return p

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.

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

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

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

Pilihan[sunting sumber]

Pilihan berikut ada. Ianya dijelaskan dalam bahagian di bawah.

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

Memotong dan mengeluarkan kosong[sunting sumber]

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 trim dan removeBlanks argumen kepada false.

local args = getArgs(frame, {
	trim = false,
	removeBlanks = false
})

Pemformatan argumen khusus[sunting sumber]

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 valueFunc. Input untuk pilihan ini mestilah fungsi yang mengambil dua parameter, key dan value, dan mengembalikan satu nilai. Nilai ini adalah apa yang akan anda perolehi semasa anda memasuki lapangan key dalam args 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.

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

Contoh 2: fungsi ini membuang argumen kosong dan menukar semua argumen menjadi huruf kecil, tetapi tidak memotong ruang kosong dari posisi parameter.

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

Nota: fungsi di atas akan gagal sekiranya input yang dikeluarkan bukan jenis string atau nil. Ini mungkin berlaku jika anda menggunakan fungsi getArgs 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 p.main dan p._main, atau yang serupa).

Contoh 1 dan 2 dengan jenis pemeriksaan

Contoh 1:

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

Contoh 2:

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

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

Bingkai dan bingkai induk (parent)[sunting sumber]

Argumen dalam args 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 Modul:ExampleArgs. Modul ini mencetak dua argumen kedudukan pertama yang diluluskan.

Modul:Kod ContohArgs
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

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

Sekarang jika kita memanggil Templat:ExampleArgs, perkara berikut akan berlaku:

Kod Keputusan
{{ExampleArgs}} firstInvokeArg
{{ExampleArgs|firstTemplateArg}} firstInvokeArg
{{ExampleArgs|firstTemplateArg|secondTemplateArg}} firstInvokeArg secondTemplateArg

Terdapat tiga pilihan yang boleh anda tetapkan untuk mengubah tingkah laku ini:frameOnly, parentOnly dan parentFirst. Jika anda menetapkan frameOnly maka hanya argumen yang diluluskan dari kerangka semasa yang akan diterima; jika anda menetapkan parentOnly maka hanya argumen yang dikeluarkan dari bingkai induk yang akan diterima; dan jika anda menetapkan parentFirst 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 Templat:ExampleArgs:

frameOnly
Kod Keputusan
{{ExampleArgs}} firstInvokeArg
{{ExampleArgs|firstTemplateArg}} firstInvokeArg
{{ExampleArgs|firstTemplateArg|secondTemplateArg}} firstInvokeArg
parentOnly
Kod Keputusan
{{ExampleArgs}}
{{ExampleArgs|firstTemplateArg}} firstTemplateArg
{{ExampleArgs|firstTemplateArg|secondTemplateArg}} firstTemplateArg secondTemplateArg
parentFirst
Kod Keputusan
{{ExampleArgs}} firstInvokeArg
{{ExampleArgs|firstTemplateArg}} firstTemplateArg
{{ExampleArgs|firstTemplateArg|secondTemplateArg}} firstTemplateArg secondTemplateArg

Nota:

  1. Jika anda menetapkan kedua-dua pilihan frameOnly dan parentOnly, modul tidak akan sama sekali mengeluarkan argumen dari #invoke. Ini mungkin bukan yang anda mahukan.
  2. 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 parentFirst dan frameOnly tidak akan memberi kesan..

Wrappers[sunting sumber]

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 <noinclude>...</noinclude> tags) is {{#invoke:Side box|main}}. 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 |text=Some text in the code {{#invoke:Side box|main|text=Some text}} would be ignored completely, no matter what page it was used from. By using the wrappers option to specify 'Template:Side box' as a wrapper, we can make {{#invoke:Side box|main|text=Some text}} 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.

local args = getArgs(frame, {
	wrappers = 'Template:Wrapper template'
})


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

Notes:

  1. 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.
  2. 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.
  3. If the wrappers option is set and no parent frame is available, the module will always get the arguments from the frame passed to getArgs.

Menulis di meja/jadual args[sunting sumber]

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.)

args.foo = 'some value'

Adalah mungkin untuk mengubah tingkah laku ini dengan pilihan readOnly dan noOverwrite. Jika readOnly diatur maka tidak mustahil untuk menulis nilai ke meja/jadual argumen sama sekali. Jika noOverwrite 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[sunting sumber]

This module uses metatables to fetch arguments from #invoke. This allows access to both the frame arguments and the parent frame arguments without using the pairs() function. This can help if your module might be passed <ref>...</ref> tags as input.

As soon as <ref>...</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 pairs() 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 pairs(args) elsewhere in your module, however.

Batasan yang diketahui[sunting sumber]

Penggunaan metatables juga mempunyai kelemahannya. Sebilangan besar alat meja Lua biasa tidak akan berfungsi dengan baik di meja args, termasuk operasi fungsi #, next(), 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.